API Reference#

The following section outlines the API of steam.py’s command extension module.

Bot#

class steam.ext.commands.Bot(**options)#

Represents a Steam bot.

This class is a subclass of Client and as a result anything that you can do with Client you can do with Bot.

Parameters:

command_prefix –
What the message content must initially contain to have a command invoked.
Can be any one of:
- str
- Iterable[str]
- Callable[[Bot, Message], Union[str, Iterable[str]]
- Callable[[Bot, Message], Awaitable[Union[str, Iterable[str]]]
Note

The first prefix matched when getting context will always be returned, ensure that no prefix matches a longer prefix later in the sequence. e.g.
```
bot = commands.Bot(command_prefix=("!", "!?"))
# the "!?" prefix will never be matched as the previous
# prefix would match the "!" at the start of the message
```
This is especially important when passing an empty string, it should always be last as no prefix after it will be matched.
owner_id – The Steam ID of the owner, this is converted to its 64 bit ID representation upon initialization.
owner_ids – The Steam IDs of the owners, these are converted to their 64 bit ID representations upon initialization.
case_insensitive – Whether or not commands should be invoke-able case insensitively.

property cogs: MappingProxyType[str, Cog[Self]]#: A read only mapping of any loaded cogs.

property extensions: mappingproxy[str, module]#: A read only mapping of any loaded extensions.

property converters: MappingProxyType[type[Any], Sequence[Converters]]#: A read only mapping of registered converters.

property help_command: HelpCommand | None#: The bot’s help command.

await close()#

Unloads any extensions and cogs, then closes the connection to Steam.

await load_extension(extension)#

Load an extension.

Parameters:: extension (str | PathLike[str]) – The name of the extension to load.
Raises:: ImportError – The extension is missing a setup function.

await unload_extension(extension)#

Unload an extension.

Parameters:: extension (str | PathLike[str]) – The name of the extension to unload.
Raises:: ModuleNotFoundError – The extension wasn’t found in the loaded extensions.

await reload_extension(extension)#

Atomically reload an extension. If any error occurs during the reload the extension will be reverted to its original state.

Parameters:: extension (str | PathLike[str]) – The name of the extension to reload.
Raises:: ModuleNotFoundError – The extension wasn’t found in the loaded extensions.

await add_cog(cog)#

Add a cog to the internal list.

Parameters:: cog (Cog[Self]) – The cog to add.

await remove_cog(cog)#

Remove a cog from the internal list.

Parameters:: cog (Cog[Self]) – The cog to remove.

add_listener(func, name=None)#

Add a function from the internal listeners list.

Parameters:

func (Callable[[~P], Coroutine[Any, Any, R]]) – The listener event to listen for.
name (str | None) – The name of the event to listen for. Defaults to func.__name__.

remove_listener(func, name=None)#

Remove a function from the internal listeners list.

Parameters:

func (Callable[[~P], Coroutine[Any, Any, R]]) – The listener to remove.
name (str | None) – The name of the event to remove. Defaults to func.__name__.

@listen(coro: CoroFuncT, /) → CoroFuncT#

@listen(name: str | None = None, /) → Callable[[F], F]

A decorator that could be called. Register a function as a listener. Calls add_listener(). Similar to Cog.listener()

Parameters:: name (str) – The name of the event to listen for. Will default to func.__name__.
Return type:: Callable[[F], F] | F

check(predicate)#

Return type:: Check[MaybeBool]

add_check(predicate)#

Add a global check to the bot.

Parameters:: predicate (Check) – The check to add.

remove_check(predicate)#

Remove a global check from the bot.

Parameters:: predicate (Check) – The check to remove.

await can_run(ctx)#

Whether or not the context’s command can be ran.

Parameters:: ctx (Context) – The invocation context.
Return type:: bool

before_invoke(coro)#

Return type:: BotInvokeT

after_invoke(coro)#

Return type:: BotInvokeT

await process_commands(message, /)#

A method to process commands for a message.

Warning

This is vital for commands to function. If you have an on_message() as a registered event using event() commands will not be dispatched. Remember to add a call to this in your on_message() event.

Parameters:: message (Message) – The message to get the context for.

await invoke(ctx)#

Invoke a command. This will parse arguments, checks, cooldowns etc. correctly.

Parameters:: ctx (Context) – The invocation context.

await get_context(message, *, cls=<class 'steam.ext.commands.context.Context'>)#

Get the context for a certain message.

Parameters:

message (Message[Any]) – The message to get the context for.
cls (type[C]) – The class to construct the context with, this is the type of the return type

Return type:

await get_prefix(message)#

Get the command prefix for a certain message.

Parameters:: message (Message) – The message to get the prefix for.
Return type:: str | None

add_command(command)#

Add a command to the internal commands list.

Parameters:: command (Command[CogT]) – The command to register.

async for ... in all_apps(*, limit=None, modified_after=None, include_games=True, include_dlc=True, include_software=True, include_videos=True, include_hardware=True)#

An asynchronous iterator over all the apps on Steam.

Parameters:

limit (int | None) – The maximum number of apps to search through. Default is None. Setting this to None will fetch all of the apps, but this will be a very slow operation.
modified_after (datetime.datetime | None) – A time to search for apps after.
include_games (bool) – Whether to include games.
include_dlc (bool) – Whether to include DLC.
include_software (bool) – Whether to include software.
include_videos (bool) – Whether to include videos.
include_hardware (bool) – Whether to include hardware.

Yields:

AppListApp

property all_commands: list[Command[CogT]]#: A list of the loaded commands.

await anonymous_login()#

Initialize a connection to a Steam CM and login anonymously.

await change_presence(*, app=None, apps=None, state=None, ui_mode=None, flags=None, force_kick=False)#

Set your status.

Parameters:

app (App | None) – An app to set your status as.
apps (Iterable[App] | None) – A list of apps to set your status to.
state (PersonaState | None) –
The state to show your account as.

Warning

Setting your status to Offline, will stop you receiving persona state updates and by extension on_user_update() will stop being dispatched.
ui_mode (UIMode | None) – The UI mode to set your status to.
flags (PersonaStateFlag | None) – The flags to update your account with.
force_kick (bool) – Whether to forcefully kick any other playing sessions.

property children: Sequence[Command[CogT]]#: The commands children.

property clans: Sequence[Clan]#: A read-only list of all the clans the connected client is in.

clear()#

Clears the internal state of the bot. After this, the bot can be considered “re-opened”, i.e. is_closed() and is_ready() both return False. This also clears the internal cache.

await code()#

Get the current steam guard code.

Warning

This will read from sys.stdin if no shared_secret was passed to login().

Return type:: str

@command(callback=None, /, *, name=None, cls=<class 'steam.ext.commands.commands.Command'>, **attrs)#

A decorator that could be called. A decorator that invokes command() and adds the created Command to the internal command list.

Parameters:

name (str | None) – The name of the command. Will default to callback.__name__.
cls (type[Command]) – The class to construct the command from. Defaults to Command.
attrs (Any) – The parameters to pass to the command’s __init__.

Returns:

The created command.

Return type:

Callable[[CoroFuncT], C] | C

property commands: set[Command[CogT]]#: A set of the loaded commands without duplicates.

await create_clan(name, /, *, abbreviation=None, community_url=None, public=True, headline=None, summary=None, language=None, country=None, state=None, city=None, apps=None, avatar=None)#

Create a clan.

Parameters:

name (str) – The name of the clan.
avatar (Media | None) – The avatar of the clan.
abbreviation (str | None) – The abbreviation of the clan.
community_url (URL_ | str | None) – The community URL of the clan.
public (bool) – Whether the clan is public.
headline (str | None) – The headline of the clan.
summary (str | None) – The summary of the clan.
language (Language | None) – The language of the clan.
country (str | None) – The country of the clan.
state (str | None) – The state of the clan.
city (str | None) – The city of the clan.
apps (Iterable[App] | None) – The apps the clan is associated with.

Return type:

Clan

await create_group(name, /, *, members, avatar=None, tagline=None)#

Create a group.

Parameters:

name (str) – The name of the group.
members (Iterable[IndividualID]) – The members to add to the group.
avatar (Media | None) – The avatar of the group.
tagline (str | None) – The tagline of the group.

Return type:

Group

await create_post(content, /, app=None)#

Create a post.

Parameters:

content (str) – The content of the post.
app (App | None) – The app to create the post for.

Return type:

Post[ClientUser]

property effects: Sequence[ClientEffect]#: A read-only list of all the effects the client has.

property emoticons: Sequence[ClientEmoticon]#: A read-only list of all the emoticons the client has.

@event(coro)#

A decorator that registers an event to listen to.

The events must be a coroutine, if not, TypeError is raised.

Usage:

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

Raises:: TypeError – The function passed is not a coroutine.
Return type:: F

await fetch_app(id, /, *, language=None)#

Fetch an app from its ID.

Parameters:

id (int) – The app id of the app.
language (Language | None) – The language to fetch the app in. If None uses the current language.

Raises:

ValueError – Passed id isn’t for a valid app.

Return type:

FetchedApp

await fetch_bundle(id, /, *, language=None)#

Fetch a bundle from its ID.

Parameters:

id (int) – The ID of the bundle.
language (Language | None) – The language to fetch the bundle in. If None uses the current language.

Return type:

FetchedBundle

await fetch_clan(id, /)#

Fetches a clan from the websocket with a matching ID.

Parameters:: id (int) – The ID64 of the clan.
Return type:: Clan

async for ... in fetch_listings(name, app)#

Fetch the listings for an item.

Parameters:

name (str) – The name of the item.
app (App) – The app the item is from.

Return type:

AsyncGenerator[Listing, None]

await fetch_package(id, /, *, language=None)#

Fetch a package from its ID.

Parameters:

id (int) – The ID of the package.
language (Language | None) – The language to fetch the package in. If None uses the current language.

Raises:

ValueError – Passed id isn’t for a valid package.

Return type:

FetchedPackage

await fetch_price(name, app, currency=None)#

Fetch the PriceOverview for an item.

Parameters:

name (str) – The name of the item.
app (App) – The app the item is from.
currency (Currency | None) – The currency to fetch the price in.

Return type:

PriceOverview

await fetch_price_history(name, app, currency=None)#

Fetch the price history for an item.

Parameters:

name (str) – The name of the item.
app (App) – The app the item is from.
currency (Currency | None) – The currency to fetch the price in.

Return type:

list[PriceHistory]

await fetch_product_info(*, apps=(), packages=())#

Fetch product info.

Parameters:

apps (Collection[App]) – The apps to fetch info on.
packages (Collection[Package]) – The packages to fetch info on.

Return type:

list[AppInfo] | list[PackageInfo] | tuple[list[AppInfo], list[PackageInfo]]

await fetch_published_file(id, /, *, revision=PublishedFileRevision.Default, language=None)#

Fetch a published file from its ID.

Parameters:

id (int) – The ID of the published file.
revision (PublishedFileRevision) – The revision of the published file to fetch.
language (Language | None) – The language to fetch the published file in. If None, the current language is used.

Return type:

PublishedFile | None

await fetch_published_files(*ids, revision=PublishedFileRevision.Default, language=None)#

Fetch published files from their IDs.

Parameters:

ids (int) – The IDs of the published files.
revision (PublishedFileRevision) – The revision of the published files to fetch.
language (Language | None) – The language to fetch the published files in. If None, the current language is used.

Return type:

list[PublishedFile | None]

await fetch_server(*, id=None, ip=None, port=None)#

Fetch a GameServer from its ip and port or its Steam ID or None if fetching the server failed.

Parameters:

ip (IPAdress | str | None) – The ip of the server.
port (int | str | None) – The port of the server.
id (int | None) – The ID64 of the game server. If passed, it makes a call to the master server to fetch its ip and port.

Note

Passing an ip, port and id to this function will raise an TypeError.

Return type:: GameServer | None

await fetch_servers(query=None, /, *, limit=100)#

Query game servers.

Parameters:

query (str | None) – The query to match servers with. If None returns all servers.
limit (int) – The maximum amount of servers to return.

See also

Query.where()

Return type:: list[GameServer]

await fetch_store_item(*, apps=(), packages=(), bundles=(), language=None)#

Fetch store items.

Parameters:

apps (Sequence[App]) – The apps to fetch store items for.
packages (Sequence[Package]) – The packages to fetch store items for.
bundles (Sequence[Bundle]) – The bundles to fetch store items for.
language (Language | None) – The language to fetch the store items in. If None, the default language is used.

Return type:

Any

await fetch_trade(id, /, *, language=None)#

Fetches a trade with a matching ID or None if the trade was not found.

Parameters:

id (int) – The ID of the trade to search for from the API.
language (Language | None) – The language to fetch the trade in. None uses the current language.

Return type:

TradeOffer[Item[User], Item[ClientUser], User] | None

await fetch_user(id, /)#

Fetches a user with a matching ID.

Parameters:: id (int) – The ID64 of the user.
Return type:: User

await fetch_users(*ids)#

Fetches a list of User.

Note

The User objects returned are unlikely to retain the order they were originally in.

Parameters:: ids (int) – The user’s ID64s.
Return type:: Sequence[User]

get_app(id, /)#

Creates a PartialApp instance from its ID.

Parameters:: id (int) – The app id of the app.
Return type:: PartialApp[None]

get_bundle(id, /)#

Creates a PartialBundle instance from its ID.

Parameters:: id (int) – The ID of the bundle.
Return type:: PartialBundle

get_clan(id, /)#

Get a clan from cache with a matching ID or None if the group was not found.

Parameters:: id (int) – The ID64 of the clan.
Return type:: Clan | None

get_cog(name)#

Get a loaded cog or None.

Parameters:: name (str) – The name of the cog.
Return type:: Cog[Self] | None

get_command(name)#

Get a command.

Parameters:: name (str) – The name of the command.
Returns:: The found command or None.
Return type:: Command[CogT] | None

get_group(id, /)#

Get a group from cache with a matching ID or None if the group was not found.

Parameters:: id (int) – The ID64 of the group.
Return type:: Group | None

get_package(id, /)#

Creates a PartialPackage from its ID.

Parameters:: id (int) – The ID of the package.
Return type:: PartialPackage

get_trade(id, /)#

Get a trade from cache with a matching ID or None if the trade was not found.

Parameters:: id (int) – The ID of the trade to search for from the cache.
Return type:: TradeOffer | None

get_user(id, /)#

Returns a user from cache with a matching ID or None if the user was not found.

Parameters:: id (int) – The ID64 of the user.
Return type:: User | None

@group(callback=None, /, *, name=None, cls=None, **attrs)#

A decorator that invokes group() and adds the created Group to the internal command list.

Parameters:

name (str | None) – The name of the command. Will default to callback.__name__.
cls (type[Group]) – The class to construct the command from. Defaults to Group.
attrs (Any) – The parameters to pass to the command’s __init__.

Returns:

The created group command.

Return type:

Callable[[CoroFuncT], G] | G

property groups: Sequence[Group]#: A read-only list of all the groups the connected client is in.

is_closed()#

Indicates if connection is closed to the WebSocket.

Return type:: bool

is_ready()#

Specifies if the client’s internal cache is ready for use.

Return type:: bool

property latency: float#: Measures latency between a heartbeat send and the heartbeat interval in seconds.

property licenses: Sequence[License]#: A read-only list of licenses the client has access to.

await login(username=None, password=None, *, shared_secret=None, identity_secret=None, refresh_token=None)#

Initialize a connection to a Steam CM and login.

If no shared_secret is passed, you will have to manually enter a Steam guard code using code().

Parameters:

username (str | None) – The username of the account to login to.
password (str | None) – The password of the account to login to.
shared_secret (str | None) – The shared secret for the account to login to.
identity_secret (str | None) – The identity secret for the account to login to.
refresh_token (str | None) – The refresh token of the account to login to.

property messages: Sequence[Message]#: A read-only list of all the messages the client has.

await on_announcement_create(announcement, /)#

Called when an announcement in a clan is created.

Parameters:: announcement (steam.Announcement) – The announcement that was created.

await on_authentication_ticket_update(ticket, response, state, /)#

Called when the client’s authentication ticket is updated.

Parameters:

ticket (steam.AuthenticationTicket) – The updated ticket.
response (steam.AuthSessionResponse) – The response code from the CM.
state (int) – The state of the ticket.

await on_clan_join(clan, /)#

Called when the client joins a new clan.

Parameters:: clan (steam.Clan) – The joined clan.

await on_clan_leave(clan, /)#

Called when the client leaves a clan.

Parameters:: clan (steam.Clan) – The left clan.

await on_clan_update(before, after, /)#

Called when a clan is updated, due to one or more of the following attributes changing:

name

avatar_url

member_count

in_game_count

online_count

active_member_count

Parameters:

before (steam.Clan) – The clan’s state before it was updated.
after (steam.Clan) – The clan’s state now.

await on_event_create(event, /)#

Called when an event in a clan is created.

Parameters:: event (steam.Event) – The event that was created.

await on_friend_add(friend, /)#

Called when a friend is added to the client’s friends list.

Parameters:: friend (steam.Friend) – The friend that was added.

await on_friend_remove(friend, /)#

Called when you or the friend remove each other from your friends lists.

Parameters:: friend (steam.Friend) – The friend who was removed.

await on_group_join(group, /)#

Called when the client joins a new group.

Parameters:: group (steam.Group) – The joined group.

await on_group_leave(group, /)#

Called when the client leaves a group.

Parameters:: group (steam.Group) – The left group.

await on_group_update(before, after, /)#

Called when a group is updated.

Parameters:

before (steam.Group) – The group’s state before it was updated.
after (steam.Group) – The group’s state now.

await on_reaction_add(reaction, /)#

Called when a reaction is added to a message.

Parameters:: reaction (MessageReaction) – The reaction that was added.

await on_reaction_remove(reaction, /)#

Called when a reaction is removed from a message.

Parameters:: reaction (MessageReaction) – The reaction that was removed.

await redeem_package(id, /)#

Redeem a promotional free licenses package from its ID.

Parameters:: id (int) – The ID of the package to redeem.
Return type:: License

property refresh_token: str | None#: The refresh token for the logged in account, can be used to login.

await register_cd_key(key, /)#

Parameters:: key (str) – The CD key to register.
Return type:: TransactionReceipt

remove_command(name)#

Remove a command from the internal commands list.

Parameters:: name (str) – The name of the command to remove.
Returns:: The removed command or None if the command was not found.
Return type:: Command[CogT] | None

run(*args, debug=False, **kwargs)#

A blocking method to start and run the client.

Shorthand for:

async def main():
    async with client:
        await client.login(...)


asyncio.run(main())

It is not recommended to subclass this method, it is normally favourable to subclass login() as it is a coroutine.

Note

This takes the same arguments as login().

Return type:: object

async for ... in search_market(query='', *, limit=100, search_description=True, sort_by='popular', reverse=True)#

https://steamcommunity.com/market/search/render?q=&descriptions=1&category_570_Hero[]=any&category_570_Slot[]=any&category_570_Type[]=any&category_570_Quality[]=tag_unique&appid=570&norender=1

Return type:: AsyncGenerator[MarketSearchItem, None]

property stickers: Sequence[ClientSticker]#: A read-only list of all the stickers the client has.

async for ... in trade_history(*, limit=100, before=None, after=None, language=None, include_failed=True)#

An asynchronous iterator for accessing a steam.ClientUser’s steam.TradeOffer objects.

Examples

Usage:

async for trade in client.trade_history(limit=10):
    items = [getattr(item, "name", str(item.id)) for item in trade.receiving]
    items = ", ".join(items) or "Nothing"
    print("Partner:", trade.user)
    print("Sent:", items)

All parameters are optional.

Parameters:

limit (int | None) – The maximum number of trades to search through. Default is 100. Setting this to None will fetch all of the user’s trades, but this will be a very slow operation.
before (datetime.datetime | None) – A time to search for trades before.
after (datetime.datetime | None) – A time to search for trades after.
language (Language | None) – The language to fetch the trade in. None uses the current language.
include_failed (bool) – Whether to include trades that failed.

Yields:

TradeOffer

await trade_url(generate_new=False)#

Fetches this account’s trade url.

Parameters:: generate_new (bool) – Whether or not to generate a new trade token, defaults to False.
Return type:: TradeURLInfo

property trades: Sequence[TradeOffer[Asset[User], Asset[ClientUser], User]]#: A read-only list of all the trades the connected client can see.

property user: ClientUser#: Represents the connected client. None if not logged in.

async for ... in user_news(*, limit=None, before=None, after=None, app=None, flags=None, language=None)#

Fetch news for the user.

Parameters:

limit (int | None) – The maximum number of news entries to fetch.
before (datetime.datetime | None) – The date to fetch news before.
after (datetime.datetime | None) – The date to fetch news after.
app (App | None) – The app to fetch news entries related to.
flags (UserNewsType | None) – The type of news to fetch.
language (Language | None) – The language to fetch the news in. If None, the current language is used.

Return type:

AsyncGenerator[UserNews, None]

property users: Sequence[User]#: A read-only list of all the users the connected client can see.

await wait_for(event, *, check=<return_true>, timeout=None)#

Wait for the first event to be dispatched that meets the requirements, this by default is the first event with a matching event name.

Parameters:

event (str) – The event name from the event reference, but without the on_ prefix, to wait for.
check (Callable[[...], bool]) – A callable predicate that checks the received event. The arguments must match the parameters of the event being waited for and must return a bool.
timeout (float | None) – By default, wait_for() function does not timeout, however, in the case a timeout parameter is passed after the amount of seconds passes asyncio.TimeoutError is raised.

Raises:

asyncio.TimeoutError – If the provided timeout was reached.

Returns:

Returns None, a single argument or a tuple of multiple arguments that mirrors the parameters for the event parameter from the event reference.

Return type:

Any

await wait_until_ready()#

Waits until the client’s internal cache is all ready.

property wallet: Wallet#: The wallet info for the logged in account.

steam.ext.commands.when_mentioned(bot, message)#

A callable that implements a command prefix equivalent to being mentioned. This is meant to be passed into the Bot.command_prefix attribute.

Return type:: list[str]

steam.ext.commands.when_mentioned_or(*prefixes)#

A callable that implements when mentioned or other prefixes provided. These are meant to be passed into the Bot.command_prefix attribute.

Example

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

Note

This callable returns another callable, so if this is done inside a custom callable, you must call the returned callable, for example:

async def get_prefix(bot: commands.Bot, message: steam.Message) -> list[str]:
    extras = await prefixes_for(message.clan)  # a user defined function that returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

Event Reference#

These events function similar to the regular events, and all of the events there are also applicable to Bot. These are however unique to the commands extension module.

await steam.ext.commands.Bot.on_command_error(self, ctx, error)#

The default command error handler provided by the bot. This only fires if you do not specify any listeners for command error.

Parameters:

ctx (commands.Context) – The invocation context where the error happened.
error (Exception) – The error that was raised.

await steam.ext.commands.Bot.on_command(self, ctx, /)#

A method that is called every time a command is dispatched.

Parameters:: ctx (commands.Context) – The invocation context.

await steam.ext.commands.Bot.on_command_completion(self, ctx, /)#

A method that is called every time a command is dispatched and completed without error.

Parameters:: ctx (commands.Context) – The invocation context.

Enumerations#

class steam.ext.commands.BucketType(value)#

A enumeration that handles cooldowns.

Each attribute operates on a per x basis. So User operates on a per User basis.

Default = 0#: The default BucketType this operates on a global basis.

User = 1#: The BucketType for a steam.User.

Member = 2#: The BucketType for a steam.User and a steam.Clan.

Role = 5#: The BucketType for a steam.Role.

Channel = 6#: The BucketType for a steam.Channel.

Admin = 7#: The BucketType for a steam.Clan’s steam.Clan.admins.

ChatGroup = 8#: The BucketType for a steam.ChatGroup.

get_bucket(ctx)#

Get a bucket key for a message or context.

Parameters:: ctx (Context) – The message or context to get the bucket for.
Return type:: BucketTypeType

Commands#

@steam.ext.commands.command(callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]], /) → Command[CogT, P, R]#

@steam.ext.commands.command(**kwargs: Unpack) → Callable[[Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]], Command[CogT, P, R]]

A decorator that could be called. A decorator that turns a coroutine function into a Command.

Parameters:

name – The name of the command. Will default to callback.__name__.
cls (type[Command]) – The class to construct the command from. Defaults to Command.
attrs – The attributes to pass to the command’s __init__.

Return type:

The created command.

@steam.ext.commands.group(callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]], /) → Group[CogT, P, R]#

@steam.ext.commands.group(**kwargs: Unpack) → Callable[[Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]], Group[CogT, P, R]]

A decorator that could be called. A decorator that turns a coroutine function into a Group.

Parameters:

name – The name of the command. Will default to callback.__name__.
cls (type[Group]) – The class to construct the command from. Defaults to Group.
attrs – The attributes to pass to the command’s __init__.

Return type:

The created group command.

@steam.ext.commands.check#

A decorator that registers a function that could be a coroutine as a check to a command.

They should take a singular argument representing the Context for the message.

Examples

@commands.check
def is_mod(ctx: commands.Context) -> bool:
    return ctx.clan and ctx.author in ctx.clan.mods

@is_mod
@bot.command
async def kick(ctx: commands.Context, user: steam.User) -> None:
    ...

This will raise an steam.ext.commands.CheckFailure if the user is not an a mod in the clan.

steam.ext.commands.predicate#: The registered check, this will always be a coroutine function even if the original check wasn’t.

@steam.ext.commands.cooldown(rate, per, type=BucketType.Default)#

Give a Command’s a cooldown.

Parameters:

rate (int) – The amount of times a command can be executed before being put on cooldown.
per (float) – The amount of time to wait between cooldowns.
type (BucketType) – The bucket that the cooldown applies to.

Examples

Usage

@bot.command
@commands.cooldown(rate=1, per=10, type=commands.BucketType.User)
async def once_every_ten_seconds(ctx: commands.Context) -> None:
    ...  # this can only be invoked a user every ten seconds.

@steam.ext.commands.is_owner#

class steam.ext.commands.Command(*args, **kwargs)#

A class to represent a command.

name#: The command’s name.

help#: The command’s help docstring.

checks#: A list of the command’s checks.

cooldown#: The command’s cooldowns.

special_converters#: A list of the command’s special converters as registered by steam.ext.commands.Converter.register().

enabled#: Whether the command is enabled.

cog#: The command’s cog.

parent#: The command’s parent.

description#: The command’s description.

hidden#: Whether the command is hidden.

aliases#: The command’s aliases.

params#: The command’s parameters.

property callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]#: The internal callback the command holds.

clean_params#: The command’s parameters without "self" and "ctx".

property qualified_name: str#: The full name of the command, this takes into account subcommands.

property parents: list[Self]#: The command’s parents.

await __call__(ctx, *args, **kwargs)#

Calls the internal callback that the command holds.

Note

This bypasses all mechanisms – including checks, converters, invoke hooks, cooldowns, etc. You must take care to pass the proper arguments (excluding the parameter “self” in a cog context) and types to this function.

Return type:: R

@error(coro)#

A decorator to register a coroutine function to handle a commands on_error functionality similarly to steam.ext.commands.Bot.on_command_error().

Example:

@bot.command
async def raise_an_error(ctx: commands.Context) -> None:
    raise Exception("oh no an error")


@raise_an_error.error
async def on_error(ctx: commands.Context, error: Exception) -> None:
    await ctx.send(f"{ctx.command.name} raised an exception {error!r}")

Return type:: ErrT

before_invoke(coro)#

Return type:: InvokeT

after_invoke(coro)#

Return type:: InvokeT

await invoke(ctx)#

Invoke the callback the command holds.

Parameters:: ctx (Context) – The invocation context.

await can_run(ctx)#

Whether the command can be run.

Parameters:: ctx (Context) – The invocation context.
Return type:: bool

class steam.ext.commands.Group(*args, **kwargs)#

await __call__(ctx, *args, **kwargs)#

Calls the internal callback that the command holds.

Note

Return type:: R

add_command(command)#

Add a command to the internal commands list.

Parameters:: command (Command[CogT]) – The command to register.

after_invoke(coro)#

Return type:: InvokeT

property all_commands: list[Command[CogT]]#: A list of the loaded commands.

before_invoke(coro)#

Return type:: InvokeT

property callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]#: The internal callback the command holds.

await can_run(ctx)#

Whether the command can be run.

Parameters:: ctx (Context) – The invocation context.
Return type:: bool

property children: Sequence[Command[CogT]]#: The commands children.

clean_params#: The command’s parameters without "self" and "ctx".

@command(callback=None, /, *, name=None, cls=<class 'steam.ext.commands.commands.Command'>, **attrs)#

A decorator that could be called. A decorator that invokes command() and adds the created Command to the internal command list.

Parameters:

name (str | None) – The name of the command. Will default to callback.__name__.
cls (type[Command]) – The class to construct the command from. Defaults to Command.
attrs (Any) – The parameters to pass to the command’s __init__.

Returns:

The created command.

Return type:

Callable[[CoroFuncT], C] | C

property commands: set[Command[CogT]]#: A set of the loaded commands without duplicates.

@error(coro)#

A decorator to register a coroutine function to handle a commands on_error functionality similarly to steam.ext.commands.Bot.on_command_error().

Example:

@bot.command
async def raise_an_error(ctx: commands.Context) -> None:
    raise Exception("oh no an error")


@raise_an_error.error
async def on_error(ctx: commands.Context, error: Exception) -> None:
    await ctx.send(f"{ctx.command.name} raised an exception {error!r}")

Return type:: ErrT

get_command(name)#

Get a command.

Parameters:: name (str) – The name of the command.
Returns:: The found command or None.
Return type:: Command[CogT] | None

@group(callback=None, /, *, name=None, cls=None, **attrs)#

A decorator that invokes group() and adds the created Group to the internal command list.

Parameters:

name (str | None) – The name of the command. Will default to callback.__name__.
cls (type[Group]) – The class to construct the command from. Defaults to Group.
attrs (Any) – The parameters to pass to the command’s __init__.

Returns:

The created group command.

Return type:

Callable[[CoroFuncT], G] | G

await invoke(ctx)#

Invoke the callback the command holds.

Parameters:: ctx (Context) – The invocation context.

property parents: list[Self]#: The command’s parents.

property qualified_name: str#: The full name of the command, this takes into account subcommands.

remove_command(name)#

Remove a command from the internal commands list.

Parameters:: name (str) – The name of the command to remove.
Returns:: The removed command or None if the command was not found.
Return type:: Command[CogT] | None

Command Parsing#

steam.py offers multiple ways to parse commands.

Positional or Keyword#

Values are passed to matching parameter based on their position.

Example:

@bot.command()
async def command(ctx, argument_1, argument_2):
    ...

An invocation of !command some string would pass "some" to argument_1 and "string" to argument_2.

Variadic Positional#

Values are passed as a tuple of positional arguments that can be indefinitely long. This corresponds to an *args parameter in a function definition.

Example:

@bot.command()
async def command(ctx, argument_1, *arguments):
    ...

An invocation of !command some longer string would pass "some" to argument_1 and ("longer", "string") to arguments.

Note

This has to be the last parameter in a function definition.

Keyword only#

Any value is passed from the rest of the command to the first keyword only argument.

Example:

@bot.command()
async def command(ctx, argument_1, *, argument_2):
    ...

An invocation of !command some longer string would pass "some" to argument_1 and "longer string" to argument_2.

Note

This has to be the last parameter in a function definition.

Variadic Keyword#

Values are passed as a dict of keyword arguments that can be indefinitely long. This corresponds to a **kwargs parameter in a function definition.

Example:

@bot.command()
async def command(ctx, argument_1, **arguments):
    ...

An invocation of !command some string=long would pass "some" to argument_1 and {"string": "long"} to **arguments.

Note

This has to be the last parameter in a function definition.

Warning

Type-hinting this function does not work like it strictly should, it should be done using **kwargs: value_type whereas with steam.py it is **kwargs: dict[key_type, value_type] the rational behind this decision was to allow for non-string keys e.g. !ban user="reason to ban".

Help Commands#

class steam.ext.commands.HelpCommand(*args, **kwargs)#

The base implementation of the help command.

context: Context#: The context for the command’s invocation.

await invoke(ctx)#

Invoke the callback the command holds.

Parameters:: ctx (Context) – The invocation context.

await command_callback(ctx, *, content=None)#

The actual implementation of the help command.

This method should not directly subclassed instead you should change the behaviour through the methods that actually get dispatched:

send_cog_help()

send_command_help()

send_group_help()

command_not_found()

get_bot_mapping()#

Generate a mapping of the bot’s commands. It’s not normally necessary to subclass this. This is passed to send_help().

Return type:: Mapping[str | None, Sequence[commands.Command]]

abstractmethod await send_help(mapping)#

Send the basic help message for the bot’s command.

Parameters:: mapping (Mapping[str | None, Sequence[commands.Command]]) – The mapping from get_bot_mapping().

abstractmethod await send_cog_help(cog)#

The method called with a cog is passed as an argument.

Note

Cog names are case-sensitive.

Parameters:: cog (commands.Cog) – The cog that was passed as an argument.

abstractmethod await send_command_help(command)#

The method called when a normal command is passed as an argument.

Parameters:: command (commands.Command) – The command that was passed as an argument.

abstractmethod await send_group_help(command)#

The method called when a group command is passed as an argument.

Parameters:: command (commands.Group) – The command that was passed as an argument.

abstractmethod await command_not_found(command)#

The default implementation for when a command isn’t found.

This by default sends “The command {command} was not found.”

Parameters:: command (str) – The command that was not found.

await on_error(ctx, error)#

The default error handler for the help command. This performs the functionality as steam.ext.commands.Bot.on_command_error().

Parameters:

ctx (commands.Context) – The context for the invocation.
error (Exception) – The error that was raised.

await __call__(ctx, *args, **kwargs)#

Calls the internal callback that the command holds.

Note

Return type:: R

after_invoke(coro)#

Return type:: InvokeT

before_invoke(coro)#

Return type:: InvokeT

property callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]#: The internal callback the command holds.

await can_run(ctx)#

Whether the command can be run.

Parameters:: ctx (Context) – The invocation context.
Return type:: bool

clean_params#: The command’s parameters without "self" and "ctx".

@error(coro)#

A decorator to register a coroutine function to handle a commands on_error functionality similarly to steam.ext.commands.Bot.on_command_error().

Example:

@bot.command
async def raise_an_error(ctx: commands.Context) -> None:
    raise Exception("oh no an error")


@raise_an_error.error
async def on_error(ctx: commands.Context, error: Exception) -> None:
    await ctx.send(f"{ctx.command.name} raised an exception {error!r}")

Return type:: ErrT

property parents: list[Self]#: The command’s parents.

property qualified_name: str#: The full name of the command, this takes into account subcommands.

class steam.ext.commands.DefaultHelpCommand(*args, **kwargs)#

The default implementation of the help command.

await send_help(mapping)#

Send the basic help message for the bot’s command.

Parameters:: mapping (Mapping[str | None, Sequence[commands.Command]]) – The mapping from get_bot_mapping().

await send_cog_help(cog)#

The method called with a cog is passed as an argument.

Note

Cog names are case-sensitive.

Parameters:: cog (commands.Cog) – The cog that was passed as an argument.

await send_command_help(command)#

The method called when a normal command is passed as an argument.

Parameters:: command (commands.Command) – The command that was passed as an argument.

await send_group_help(command)#

The method called when a group command is passed as an argument.

Parameters:: command (commands.Group) – The command that was passed as an argument.

await __call__(ctx, *args, **kwargs)#

Calls the internal callback that the command holds.

Note

Return type:: R

after_invoke(coro)#

Return type:: InvokeT

before_invoke(coro)#

Return type:: InvokeT

property callback: Callable[[Concatenate[CogT, Context[Any], P]], Coroutine[Any, Any, R]] | Callable[[Concatenate[Context[Any], P]], Coroutine[Any, Any, R]]#: The internal callback the command holds.

await can_run(ctx)#

Whether the command can be run.

Parameters:: ctx (Context) – The invocation context.
Return type:: bool

clean_params#: The command’s parameters without "self" and "ctx".

await command_callback(ctx, *, content=None)#

The actual implementation of the help command.

This method should not directly subclassed instead you should change the behaviour through the methods that actually get dispatched:

send_cog_help()

send_command_help()

send_group_help()

command_not_found()

await command_not_found(command)#

The default implementation for when a command isn’t found.

This by default sends “The command {command} was not found.”

Parameters:: command (str) – The command that was not found.

@error(coro)#

A decorator to register a coroutine function to handle a commands on_error functionality similarly to steam.ext.commands.Bot.on_command_error().

Example:

@bot.command
async def raise_an_error(ctx: commands.Context) -> None:
    raise Exception("oh no an error")


@raise_an_error.error
async def on_error(ctx: commands.Context, error: Exception) -> None:
    await ctx.send(f"{ctx.command.name} raised an exception {error!r}")

Return type:: ErrT

get_bot_mapping()#

Generate a mapping of the bot’s commands. It’s not normally necessary to subclass this. This is passed to send_help().

Return type:: Mapping[str | None, Sequence[commands.Command]]

await invoke(ctx)#

Invoke the callback the command holds.

Parameters:: ctx (Context) – The invocation context.

await on_error(ctx, error)#

The default error handler for the help command. This performs the functionality as steam.ext.commands.Bot.on_command_error().

Parameters:

ctx (commands.Context) – The context for the invocation.
error (Exception) – The error that was raised.

property parents: list[Self]#: The command’s parents.

property qualified_name: str#: The full name of the command, this takes into account subcommands.

context: Context#: The context for the command’s invocation.

Cogs#

class steam.ext.commands.Cog#

A class from which Cogs can be created. These are used to separate commands and listeners into separate files.

qualified_name#

The name of the cog. Can be set in a subclass e.g.

class MyCog(commands.Cog, name="SpecialCogName"):
    ...

Defaults to Cog.__name__.

Type:: Final[str]

command_attrs#

Attributes to pass to every command registered in the cog. Can be set in subclass e.g.

class MyBrokenCog(commands.Cog, command_attrs=dict(enabled=False)):
    # all the commands by default would be disabled

    @commands.command()
    async def broken(self, ctx):  # disabled
        ...

    @commands.command(enabled=True)
    async def working(self, ctx):  # enabled
        ...

Type:: Final[Mapping[str, Any]]

description#

The cleaned up doc-string for the cog.

Type:: Final[str | None]

commands: Final#: A set of the cog’s commands.

listeners: Final#: A list of tuples of the events registered with the format (name, listener)

classmethod @listener(coro: F, /) → F#

classmethod @listener(name: str | None = None, /) → Callable[[F], F]

A decorator that could be called. Register a coroutine function as a listener. Similar to listen().

Parameters:: name – The name of the event to listen for. Defaults to func.__name__.
Return type:: Callable[[F], F] | F

await cog_command_error(ctx, error)#

A special method that is called when an error is dispatched inside this cog. This is similar to on_command_error() except it only applies to the commands inside this cog.

Parameters:

ctx (commands.Context[Bot]) – The invocation context where the error happened.
error (Exception) – The error that happened.

await cog_check(ctx)#

A special method that registers as a commands.check() for every command and subcommand in this cog.

Parameters:: ctx (commands.Context[Bot]) – The invocation context.
Return type:: bool

await bot_check(ctx)#

A special method that registers as a commands.Bot.check() globally.

Parameters:: ctx (commands.Context[Bot]) – The invocation context.
Return type:: bool

await cog_unload()#

A special method that is called when the cog gets removed.

This is called before teardown().

Context#

class steam.ext.commands.Context(bot, message, lex, prefix, command=None, invoked_with=None)#

Represents the context of a command.

message#: The message the context was generated from.

prefix#: The prefix of the message the context was generated from

author#: The author of the message.

channel#: The channel the message was sent in.

clan#: The clan the message was sent in None if the message wasn’t sent in a clan.

group#: The group the message was sent in None if the message wasn’t sent in a group.

bot#: The bot instance.

command#: The command the context is attached to.

cog#: The cog the command is in.

await invoke()#

A shortcut method that invokes the current context using invoke().

Equivalent to

await ctx.command.invoke(ctx)

history(*, limit=100, before=None, after=None)#

A shortcut method that gets the current channel’s history.

Equivalent to

ctx.channel.history(**kwargs)

Return type:: AsyncGenerator[Message[PartialUser], None]

property valid: bool#: Whether or not the context could be invoked.

await fetch_message(id, /)#

Fetch a message by its Message.id.

Return type:: MessageT | None

await send(content=..., /, *, media=None)#

Send a message to a certain destination.

Parameters:

content (Any) – The content of the message to send.
media (Media | None) – The media to send to the user.

Note

Anything as passed to content is implicitly cast to a str.

Raises:

HTTPException – Sending the message failed.
Forbidden – You do not have permission to send the message.

Returns:

The sent message, only applicable if content is passed.

Return type:

MessageT | None

Cooldowns#

class steam.ext.commands.Cooldown(rate, per, bucket)#

The class that holds a command’s cooldown.

bucket: BucketType#: The bucket that should be used to determine this command’s cooldown.

reset()#

Reset the command’s cooldown.

get_retry_after(bucket, now)#

Get the retry after for a command.

Parameters:

bucket (BucketTypeType) – The bucket to find in the cache.
now (float) – The UNIX timestamp to find times after.

Return type:

float

Converters#

@steam.ext.commands.converter#

The recommended way to mark a function converter as such.

Note

All of the converters marked with this decorator or derived from Converter can be accessed via converters.

Examples

@commands.converter
def command_converter(argument: str) -> commands.Command:  # this is the type hint used
    return bot.get_command(argument)

# then later
@bot.command
async def source(ctx, command: commands.Command):  # this then calls command_converter on invocation.
    ...

steam.ext.commands.converter_for#

The class that the converter can be type-hinted to to.

Type:: T

class steam.ext.commands.Converter#

A custom typing.Protocol from which converters can be derived.

Note

All of the converters derived from Converter or marked with the converter_for() decorator can be accessed via converters.

Some custom dataclasses from this library can be type-hinted without the need for a custom converter:

User.

Channel

Clan

Group

App

Examples

Builtin:

@bot.command
async def command(ctx, user: steam.User):
    ...  # this will tell the parser to convert user from a str to a steam.User object.

# invoked as
# !command 76561198248053954
# or !command Gobot1234

A custom converter:

class MediaConverter(commands.Converter[steam.Media]):  # the annotation to typehint to
    async def convert(self, ctx: commands.Context, argument: str) -> steam.Media:
        async with aiohttp.ClientSession() as session:
            async with session.get(argument) as r:
                media_bytes = BytesIO(await r.read())
        try:
            return steam.Media(media_bytes)
        except (TypeError, ValueError):  # failed to convert to an media
            raise commands.BadArgument("Cannot convert media") from None


# then later
@bot.command
async def set_avatar(ctx: commands.Context, avatar: steam.Media) -> None:
    await bot.user.edit(avatar=avatar)
    await ctx.send("👌")


# invoked as
# !set_avatar https://my_image_url.com

classmethod register(command)#

Examples

class CustomUserConverter(commands.Converter[steam.User]):
    async def convert(self, ctx: commands.Context, argument: str) -> steam.User:
        ...

@bot.command
@CustomUserConverter.register
async def is_cool(ctx, user: steam.User):
    ...

In this example is_cool’s user parameter would be registered to the CustomUserConverter rather than the global UserConverter.

Return type:: MaybeCommandT

class steam.ext.commands.UserConverter#

The converter that is used when the type-hint passed is User.

Lookup is in the order of:

Steam ID
Mentions
Name
URLs

class steam.ext.commands.ChannelConverter#

The converter that is used when the type-hint passed is Channel.

Lookup is in the order of:

ID
Name

class steam.ext.commands.ClanConverter#

The converter that is used when the type-hint passed is Clan.

Lookup is in the order of:

Steam ID
Name
URLs

class steam.ext.commands.GroupConverter#

The converter that is used when the type-hint passed is Group.

Lookup is in the order of:

ID
Name

class steam.ext.commands.AppConverter#

The converter that is used when the type-hint passed is App.

If the param is a digit it is assumed that the argument is the App.id else it is assumed it is the App.name.

Default Values#

class steam.ext.commands.Default#

A custom way to specify a default values for commands.

Examples

Builtin:

@bot.command()
async def info(ctx, user=DefaultAuthor):
    ...  # if no user is passed it will be ctx.author

A custom default:

class CurrentCommand(commands.Default):
    async def default(self, ctx: commands.Context) -> commands.Command:
        return ctx.command  # return the current command

# then later
@bot.command
async def source(ctx: commands.Context, command: commands.Command = CurrentCommand):
    ...  # command would now be source


# this could also be mixed in with a converter to convert a string to a command.

class steam.ext.commands.DefaultAuthor#: Returns the Context.author

class steam.ext.commands.DefaultChannel#: Returns the Context.channel

class steam.ext.commands.DefaultClan#: Returns the Context.clan

class steam.ext.commands.DefaultGroup#: Returns the Context.group

class steam.ext.commands.DefaultApp#: Returns the Context.author’s app

Greedy#

final class steam.ext.commands.Greedy#

A custom typing.Generic that allows for special greedy command parsing behaviour. It signals to the command parser to consume as many arguments as it can until it silently errors reverts the last argument being read and then carries on normally.

Greedy can be mixed in with any normally supported positional or keyword argument type any number of times.

Example

@bot.command()
async def test(ctx, numbers: commands.Greedy[int], reason: str):
    await ctx.send(f"numbers: {numbers}, reason: {reason}")

An invocation of "test 1 2 3 4 5 6 hello" would pass (1, 2, 3, 4, 5, 6) to numbers and "hello" to reason.

converter#: alias of Any

classmethod __class_getitem__(converter)#

The entry point for creating a Greedy type.

Return type:: Self

Exceptions#

exception steam.ext.commands.CommandError#

Base Exception for errors raised by commands.

Subclass of SteamException.

exception steam.ext.commands.BadArgument#

Exception raised when a bad argument is passed to a command.

Subclass of CommandError.

exception steam.ext.commands.MissingRequiredArgument(param)#

Exception raised when a required argument is not passed to a command.

Subclass of BadArgument.

param#: The argument that is missing.

exception steam.ext.commands.DuplicateKeywordArgument(name)#

Exception raised when a keyword argument passed would shadow another.

Subclass of BadArgument.

name#: The argument that would shadow another.

exception steam.ext.commands.UnmatchedKeyValuePair#

Exception raised when an incorrect number of key value pairs are passed to a command to be unpacked.

Subclass of BadArgument.

exception steam.ext.commands.CheckFailure#

Base Exception raised when a check fails.

Subclass of CommandError.

exception steam.ext.commands.NotOwner#

Exception raised if the user does not own the bot.

Subclass of CheckFailure.

exception steam.ext.commands.CommandNotFound#

Exception raised when a command is not found.

Subclass of CommandError.

exception steam.ext.commands.CommandDisabled(command)#

Exception raised when a command is disabled and is attempted to be ran.

Subclass of CheckFailure.

command#: The command that has been disabled.

exception steam.ext.commands.CommandOnCooldown(retry_after)#

Exception raised when a command is still on cooldown.

Subclass of CommandError.

retry_after#: The time in seconds at which that the next command can successfully be executed.

Exception Hierarchy#

steam.SteamException
- CommandError
  
  BadArgument
  
  MissingRequiredArgument
  
  DuplicateKeywordArgument
  
  UnmatchedKeyValuePair
  
  CommandNotFound
  
  CheckFailure
  
  CommandDisabled
  
  NotOwner
  
  CommandOnCooldown