Bots¶

The following section documents everything related to bot system.

BaseBot¶

Attributes

id
state

Methods

async delete
async edit

class stoat.BaseBot(*, state, id)[source]¶

Represents a base bot on Stoat.

This inherits from Base.

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the bot.

Fires UserUpdateEvent for all users who are subscribed <server_subscriptions>_ to bot user.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, name=UNDEFINED, public=UNDEFINED, analytics=UNDEFINED, interactions_url=UNDEFINED, oauth2=UNDEFINED, reset_oauth2_client_secret=False, reset_token=False)[source]¶

This function is a coroutine.

Edits the bot.

Fires UserUpdateEvent for all users who are subscribed to bot user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new bot name. Must be between 2 and 32 characters and not contain whitespace characters.
public (UndefinedOr[bool]) – Whether the bot should be public (could be invited by anyone).
analytics (UndefinedOr[bool]) – Whether to allow Stoat collect analytics about the bot.
interactions_url (UndefinedOr[Optional[str]]) – The new bot interactions URL. For now, this parameter is reserved and does not do anything.
oauth2 (UndefinedOr[Optional[BotOAuth2Edit]]) – The new bot’s OAuth2 settings.
reset_oauth2_client_secret (bool) – Whether to reset bot’s OAuth2 client secret. The new client secret can be accessed via BotOAuth2.secret.
reset_token (bool) – Whether to reset bot token. The new token can be accessed via bot.token.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The bot’s name exceeded length or contained whitespace.

InvalidUsername

The bot’s name had forbidden characters/substrings.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated bot.

Return type:

Bot

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

Bot¶

Attributes

analytics
discoverable
flags
id
interactions_url
oauth2
owner
owner_id
privacy_policy_url
public
raw_flags
state
terms_of_service_url
token
user

Methods

async delete
async edit
def get_owner
def to_dict

class stoat.Bot(token, *, state, id, owner_id, public, analytics, discoverable, interactions_url, terms_of_service_url, privacy_policy_url, oauth2, raw_flags, user)[source]¶

Represents a bot on Stoat.

This inherits from BaseBot.

owner_id¶

The user’s ID who owns this bot.

Type:: str

token¶

The bot’s token used to authenticate requests.

Type:: str

public¶

Whether the bot is public (may be invited by anyone).

Type:: bool

analytics¶

Whether to enable analytics.

Type:: bool

discoverable¶

Whether the bot is publicly discoverable.

Type:: bool

interactions_url¶

The URL to send interactions to.

Note

This attribute is reserved.

Type:: Optional[str]

terms_of_service_url¶

The Terms of Service’s URL.

Type:: Optional[str]

privacy_policy_url¶

The privacy policy URL.

Type:: Optional[str]

oauth2¶

The bot’s OAuth2 settings.

Added in version 1.2.

Type:: Optional[BotOAuth2]

raw_flags¶

The bot’s flags raw value.

Type:: int

user¶

The user associated with this bot.

Type:: User

get_owner()[source]¶: Optional[User]: The user who owns this bot.

property flags[source]¶

The bot’s flags.

Type:: BotFlags

property owner[source]¶

The user who owns this bot.

Type:: User

to_dict()[source]¶: dict: Convert bot to raw data.

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the bot.

Fires UserUpdateEvent for all users who are subscribed <server_subscriptions>_ to bot user.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the bot.

Fires UserUpdateEvent for all users who are subscribed to bot user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new bot name. Must be between 2 and 32 characters and not contain whitespace characters.
public (UndefinedOr[bool]) – Whether the bot should be public (could be invited by anyone).
analytics (UndefinedOr[bool]) – Whether to allow Stoat collect analytics about the bot.
interactions_url (UndefinedOr[Optional[str]]) – The new bot interactions URL. For now, this parameter is reserved and does not do anything.
oauth2 (UndefinedOr[Optional[BotOAuth2Edit]]) – The new bot’s OAuth2 settings.
reset_oauth2_client_secret (bool) – Whether to reset bot’s OAuth2 client secret. The new client secret can be accessed via BotOAuth2.secret.
reset_token (bool) – Whether to reset bot token. The new token can be accessed via bot.token.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The bot’s name exceeded length or contained whitespace.

InvalidUsername

The bot’s name had forbidden characters/substrings.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated bot.

Return type:

Bot

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

PublicBot¶

Attributes

description
id
internal_avatar_id
name
state

Methods

async delete
async edit
def to_dict

class stoat.PublicBot(*, state, id, name, internal_avatar_id, description)[source]¶

Represents public bot on Stoat.

This inherits from BaseBot.

name¶

The bot’s name.

Type:: str

internal_avatar_id¶

The bot’s avatar ID.

Type:: Optional[str]

description¶

The bot’s description.

Type:: str

to_dict()[source]¶: dict: Convert public bot to raw data.

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the bot.

Fires UserUpdateEvent for all users who are subscribed <server_subscriptions>_ to bot user.

Note

This can only be used by non-bot accounts.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

This function is a coroutine.

Edits the bot.

Fires UserUpdateEvent for all users who are subscribed to bot user.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new bot name. Must be between 2 and 32 characters and not contain whitespace characters.
public (UndefinedOr[bool]) – Whether the bot should be public (could be invited by anyone).
analytics (UndefinedOr[bool]) – Whether to allow Stoat collect analytics about the bot.
interactions_url (UndefinedOr[Optional[str]]) – The new bot interactions URL. For now, this parameter is reserved and does not do anything.
oauth2 (UndefinedOr[Optional[BotOAuth2Edit]]) – The new bot’s OAuth2 settings.
reset_oauth2_client_secret (bool) – Whether to reset bot’s OAuth2 client secret. The new client secret can be accessed via BotOAuth2.secret.
reset_token (bool) – Whether to reset bot token. The new token can be accessed via bot.token.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The bot’s name exceeded length or contained whitespace.

InvalidUsername

The bot’s name had forbidden characters/substrings.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
NotFound – Possible values for type:

Value

Reason

NotFound

The bot was not found, or the current user does not own bot.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated bot.

Return type:

Bot

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

BotOAuth2¶

Attributes

allowed_scopes
public
redirect_uris
secret

class stoat.BotOAuth2(*, public, secret, redirect_uris, allowed_scopes)[source]¶

Represents how the bot does use OAuth2.

Added in version 1.2.

public¶

Whether bot users do not need to invoke server to exchange code.

Type:: bool

secret¶

The client secret, only available if public is False.

Type:: Optional[str]

redirect_uris¶

The whitelisted URIs for redirecting to during OAuth2 authorization.

Type:: List[str]

allowed_scopes¶

A mapping of OAuth2 scopes to reasoning why would it be requested.

Type:: Dict[str, OAuth2ScopeReasoning]

BotOAuth2Edit¶

Attributes

allowed_scopes
public
redirect_uris

class stoat.BotOAuth2Edit(*, public=UNDEFINED, redirect_uris=UNDEFINED, allowed_scopes=UNDEFINED)[source]¶

Represents new bot’s OAuth2 settings.

Added in version 1.2.

public¶

Whether the bot is a public client.

Type:: UndefinedOr[bool

redirect_uris¶

The whitelisted URIs for redirecting to during OAuth2 authorization. Must be between 1 and 10 items.

Type:: UndefinedOr[List[str]]

allowed_scopes¶

A mapping of OAuth2 scopes to reasoning why would it be requested.

Type:: UndefinedOr[Dict[Union[OAuth2Scope, str], OAuth2ScopeReasoning]]

Value	Reason
`InvalidSession`	The current bot/user token is invalid.

Value	Reason
`NotFound`	The bot was not found, or the current user does not own bot.

Value	Reason	Populated attributes
`DatabaseError`	Something went wrong during querying database.	`collection`, `operation`

Value	Reason
`FailedValidation`	The bot’s name exceeded length or contained whitespace.
`InvalidUsername`	The bot’s name had forbidden characters/substrings.