API Reference

The following section outlines the API of stoat.py.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, these logs will not be output anywhere. See Setting Up Logging for more information on how to set up and use the logging module with stoat.py.

Documents

Shard

Attributes
Methods
class stoat.Shard[source]
abstractmethod is_closed()[source]

bool: Whether the connection is closed.

abstract property base_url[source]

The base WebSocket URL.

Type:

str

abstract property bot[source]

Whether the token belongs to bot account.

Type:

bool

abstract property format[source]

The message format to use when communicating with Stoat WebSocket.

Type:

ShardFormat

abstract property handler[source]

The handler that receives events. Defaults to None if not provided.

Type:

Optional[EventHandler]

abstract property last_ping_at[source]

When the shard sent ping.

Type:

Optional[datetime]

abstract property last_pong_at[source]

When the shard received response to ping.

Type:

Optional[datetime]

abstract property logged_out[source]

Whether the shard got logged out.

Type:

bool

abstract property token[source]

The shard token. May be empty if not started.

Type:

str

abstractmethod await cleanup()[source]

Closes the aiohttp session.

abstractmethod await close()[source]

Closes the connection to Stoat.

abstract property socket[source]

The current WebSocket connection.

Type:

HTTPWebSocket

abstractmethod with_credentials(token, *, bot=True)[source]

Modifies HTTP request credentials.

Parameters:

  • token (str) – The authentication token.

  • bot (bool) – Whether the token belongs to bot account or not.

abstractmethod await authenticate()[source]

This function is a coroutine.

Authenticates the currently connected WebSocket. This is called right after successful WebSocket handshake.

abstractmethod await ping()[source]

This function is a coroutine.

Pings the WebSocket.

abstractmethod await begin_typing(channel, /)[source]

This function is a coroutine.

Begins typing in a channel.

Parameters:

channel (ULIDOr[TextableChannel]) – The channel to begin typing in.

abstractmethod await end_typing(channel, /)[source]

This function is a coroutine.

Ends typing in a channel.

Parameters:

channel (ULIDOr[TextableChannel]) – The channel to end typing in.

abstractmethod await subscribe_to(server, /)[source]

This function is a coroutine.

Subscribes user to a server. After calling this method, you will begin receiving UserUpdateEvent’s for members of the subscribed server.

Note

Calling this method has no effect on bot tokens. Additionally: - Server subscriptions automatically expire within 15 minutes. - You may have up only to 5 active subscriptions. - This command should only be sent if application/client is in focus. - You should aim to call this method at most every 10 minutes per server.

Parameters:

server (ULIDOr[BaseServer]) – The server to subscribe to.

abstractmethod await begin_editing(channel, message)[source]

This function is a coroutine.

Begins editing a message.

Parameters:

  • channel (ULIDOr[TextableChannel]) – The channel the message was sent in.

  • message (ULIDOr[BaseMessage]) – The message to begin editing.

abstractmethod await stop_editing(channel, message)[source]

This function is a coroutine.

Stops editing a message.

Parameters:

  • channel (ULIDOr[TextableChannel]) – The channel the message was sent in.

  • message (ULIDOr[BaseMessage]) – The message to stop editing.

abstractmethod await connect()[source]

Starts the WebSocket lifecycle.

ShardImpl

Attributes
Methods
class stoat.ShardImpl(token, *, adapter=None, base_url=None, bot=True, connect_delay=2, format=('json', 'json'), handler=None, reconnect_on_timeout=True, request_user_settings=None, retries=None, state, user_agent=None)[source]

Implements Stoat WebSocket client.

base_url[source]

The base WebSocket URL.

Type:

str

bot[source]

Whether the token belongs to bot account. Defaults to True.

Type:

bool

connect_delay

The duration in seconds to sleep when reconnecting to WebSocket due to aiohttp errors. Defaults to 2.

Type:

Optional[float]

format[source]

The message format to use when communicating with Stoat WebSocket.

Type:

ShardFormat

handler[source]

The handler that receives events. Defaults to None if not provided.

Type:

Optional[EventHandler]

last_ping_at[source]

When the shard sent ping.

Type:

Optional[datetime]

last_pong_at[source]

When the shard received response to ping.

Type:

Optional[datetime]

logged_out[source]

Whether the shard got logged out.

Type:

bool

reconnect_on_timeout

Whether to reconnect when received pong nonce is not equal to current ping nonce. Defaults to True.

Type:

bool

request_user_settings

The list of user setting keys to request.

Type:

Optional[List[str]]

state

The state.

Type:

State

token[source]

The shard token. May be empty if not started.

Type:

str

user_agent

The HTTP user agent used when connecting to WebSocket.

Type:

str

is_closed()[source]

bool: Whether the connection is closed.

property base_url[source]

The base WebSocket URL.

Type:

str

property bot[source]

Whether the token belongs to bot account.

Type:

bool

property format[source]

The message format to use when communicating with Stoat WebSocket.

Type:

ShardFormat

property handler[source]

The handler that receives events. Defaults to None if not provided.

Type:

Optional[EventHandler]

property last_ping_at[source]

When the shard sent ping.

Type:

Optional[datetime]

property last_pong_at[source]

When the shard received response to ping.

Type:

Optional[datetime]

property logged_out[source]

Whether the shard got logged out.

Type:

bool

property token[source]

The shard token. May be empty if not started.

Type:

str

await cleanup()[source]

This function is a coroutine.

Closes the aiohttp session.

await close()[source]

This function is a coroutine.

Closes the connection to Stoat.

property socket[source]

The current WebSocket connection.

Type:

HTTPWebSocket

with_credentials(token, *, bot=True)[source]

Modifies HTTP request credentials.

Parameters:

  • token (str) – The authentication token.

  • bot (bool) – Whether the token belongs to bot account or not.

await authenticate()[source]

This function is a coroutine.

Authenticates the currently connected WebSocket. This is called right after successful WebSocket handshake.

await ping()[source]

This function is a coroutine.

Pings the WebSocket.

await begin_typing(channel, /)[source]

This function is a coroutine.

Begins typing in a channel.

Parameters:

channel (ULIDOr[TextableChannel]) – The channel to begin typing in.

await end_typing(channel, /)[source]

This function is a coroutine.

Ends typing in a channel.

Parameters:

channel (ULIDOr[TextableChannel]) – The channel to end typing in.

await subscribe_to(server, /)[source]

This function is a coroutine.

Subscribes user to a server. After calling this method, you will begin receiving UserUpdateEvent’s for members of the subscribed server.

Note

Calling this method has no effect on bot tokens. Additionally: - Server subscriptions automatically expire within 15 minutes. - You may have up only to 5 active subscriptions. - This command should only be sent if application/client is in focus. - You should aim to call this method at most every 10 minutes per server.

Parameters:

server (ULIDOr[BaseServer]) – The server to subscribe to.

await begin_editing(channel, message)[source]

This function is a coroutine.

Begins editing a message.

Parameters:

  • channel (ULIDOr[TextableChannel]) – The channel the message was sent in.

  • message (ULIDOr[BaseMessage]) – The message to begin editing.

await stop_editing(channel, message)[source]

This function is a coroutine.

Stops editing a message.

Parameters:

  • channel (ULIDOr[TextableChannel]) – The channel the message was sent in.

  • message (ULIDOr[BaseMessage]) – The message to stop editing.

get_headers()[source]

Dict[str, str]: The headers to use when connecting to WebSocket.

await connect()[source]

Starts the WebSocket lifecycle.

EventHandler

Methods
class stoat.EventHandler[source]

A handler for shard events.

abstractmethod handle_raw(shard, payload, /)[source]

Handles dispatched event.

Parameters:

  • shard (Shard) – The shard that received the event.

  • payload (Dict[str, Any]) – The received event payload.

before_connect(shard, /)[source]

Called before connecting to Stoat.

after_connect(shard, socket, /)[source]

Called when successfully connected to Stoat WebSocket.

Parameters:

socket (HTTPWebSocket) – The connected WebSocket.

State

Attributes
Methods
class stoat.State(*, cache=None, provide_cache_context_in=None, shard=None)[source]

Represents a manager for all stoat.py objects.

provide_cache_context_in

The methods/properties that do provide cache context.

Type:

List[ProvideCacheContextIn]

parser

The parser.

Type:

Parser

system

The Stoat#0000 sentinel user.

Type:

User

voice_url

The URL to voice server.

Type:

str

property cache[source]

The cache attacted to this state.

Type:

Optional[Cache]

property cdn_client[source]

The CDN client attached to this state.

Type:

CDNClient

property http[source]

The HTTP client attached to this state.

Type:

HTTPClient

property shard[source]

The shard attached to this state.

Type:

Shard

property me[source]

The currently logged in user.

Type:

Optional[OwnUser]

property my_id[source]

Returns the currently logged in user’s ID, or empty string if unavailable.

Type:

str

property saved_notes[source]

The Saved Notes channel.

Type:

Optional[SavedMessagesChannel]

property settings[source]

The current user settings.

Type:

UserSettings

get_channel(channel_id, /)[source]

PartialMessageable: Returns the partial messageable for provided ID.

get_server(server_id, /)[source]

BaseServer: Returns the base server for provided ID.

get_user(user_id, /)[source]

BaseUser: Returns the base user for provided ID.

provide_cache_context(place, /)[source]

bool: Whether to provide cache context in that place or not.

Parameters:

place (ProvideCacheContextIn) – The place the cache context is going to be created in.

CDNClient

Attributes
Methods
class stoat.CDNClient(*, base=None, adapter=None, state, user_agent=None)[source]

Represents a HTTP client sending HTTP requests to the Stoat Autumn API.

state

The state.

Type:

State

user_agent

The HTTP user agent used when making requests.

Type:

str

property base[source]

The base URL.

Type:

str

property bot[source]

Whether the token belongs to bot account.

Type:

bool

property oauth2[source]

Whether the token is an OAuth2 access token.

Type:

bool

property token[source]

The token in use. May be empty if not started.

Type:

str

url_for(id, tag)[source]

str: Generates asset URL.

Parameters:

  • id (str) – The asset’s ID.

  • tag (Tag) – The asset’s tag.

await preview(tag, id)[source]

This function is a coroutine.

Preview an asset. Only applicable for images.

Parameters:

  • tag (str) – The asset’s tag.

  • id (str) – The asset’s ID.

Returns:

The preview in webp format.

Return type:

bytes

await read(tag, id, filename='original')[source]

This function is a coroutine.

Read asset contents.

Parameters:

  • tag (str) – The asset’s tag.

  • id (str) – The asset’s ID.

  • filename (str) – The asset’s filename. A special value of original can be used to retrieve asset by ID. Defaults to original.

Returns:

The asset contents.

Return type:

bytes

await upload(tag, data)[source]

This function is a coroutine.

Uploads a file to CDN.

Parameters:

  • tag (str) – The asset’s tag.

  • data (aiohttp.FormData) – The asset’s contents to upload. Form must have a field called file.

Returns:

The asset ID.

Return type:

str

Tag

class stoat.Tag

An alias to typing.Literal with available CDN tags.

Resource

Methods
class stoat.Resource[source]
abstractmethod await upload(cdn_client, tag, /)[source]

str: Uploads the resource to CDN, then returns ID.

Parameters:

  • cdn_client (CDNClient) – The CDN client to use.

  • tag (Tag) – The tag to upload resource to.

Upload

Attributes
Methods
class stoat.Upload(content, *, tag=None, filename)[source]

Represents a file upload.

This inherits from Resource.

content

The file contents.

Type:

Union[bytes, IOBase]

tag

The attachment tag. If none, this is determined automatically.

Type:

Optional[Tag]

filename

The file name.

Type:

str

classmethod attachment(content, *, filename)[source]

Creates an upload with 'attachments' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

classmethod avatar(content, *, filename)[source]

Creates an upload with 'avatars' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

classmethod background(content, *, filename)[source]

Creates an upload with 'backgrounds' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

classmethod banner(content, *, filename)[source]

Creates an upload with 'banners' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

classmethod emoji(content, *, filename)[source]

Creates an upload with 'emojis' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

classmethod icon(content, *, filename)[source]

Creates an upload with 'icons' tag.

Parameters:

  • content (Union[bytes, IOBase]) – The content to upload.

  • filename (str) – The filename.

Returns:

The constructed upload.

Return type:

Upload

await upload(cdn_client, tag, /)[source]

str: Uploads the resource to CDN, then returns ID.

Parameters:

  • cdn_client (CDNClient) – The CDN client to use.

  • tag (Tag) – The tag to upload resource to.

Content

class stoat.Content

An union of types that can be resolved into content.

The following classes are included in this union:

stoat.resolve_content(content, /)[source]

ResolvableResource

class stoat.ResolvableResource

An union of types that can be resolved into resource.

The following classes are included in this union:

await stoat.resolve_resource(state, resolvable, /, *, tag)[source]

Resolve a resource.

Parameters:
Returns:

The uploaded file ID.

Return type:

str

Parser

Attributes
Methods
class stoat.Parser(*, state)[source]

An factory that produces wrapper objects from raw data.

state

The state the parser is attached to.

Type:

State

parse_apple_music_embed_special(payload, /)[source]

Parses an Apple Music embed special content object.

Parameters:

payload (Dict[str, Any]) – The Apple Music embed special content payload to parse.

Returns:

The parsed Apple Music embed special content object.

Return type:

AppleMusicEmbedSpecial

parse_asset_metadata(d, /)[source]

Parses an asset metadata object.

Parameters:

payload (Dict[str, Any]) – The asset metadata payload to parse.

Returns:

The parsed asset metadata object.

Return type:

AssetMetadata

parse_asset(d, /)[source]

Parses an asset object.

Parameters:

payload (Dict[str, Any]) – The asset payload to parse.

Returns:

The parsed asset object.

Return type:

StatelessAsset

parse_auth_event(shard, payload, /)[source]

Parses an Auth event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed authifier event object.

Return type:

AuthifierEvent

parse_authenticated_event(shard, payload, /)[source]

Parses an Authenticated event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed authenticated event object.

Return type:

AuthenticatedEvent

parse_ban(payload, users, /)[source]

Parses a ban object.

Parameters:

  • payload (Dict[str, Any]) – The ban payload to parse.

  • users (Dict[str, DisplayUser]) – The users associated with the ban.

Returns:

The parsed ban object.

Return type:

Ban

parse_bandcamp_embed_special(payload, /)[source]

Parses a Bandcamp embed special content object.

Parameters:

payload (Dict[str, Any]) – The Bandcamp embed special content payload to parse.

Returns:

The parsed Bandcamp embed special content object.

Return type:

BandcampEmbedSpecial

parse_bans(payload, /)[source]

Parses an object with bans and associated banned users.

Parameters:

payload (Dict[str, Any]) – The list payload to parse.

Returns:

The parsed ban objects.

Return type:

List[Ban]

parse_bot(payload, user, /)[source]

Parses a bot object.

Parameters:

  • payload (Dict[str, Any]) – The bot payload to parse.

  • user (raw.User) – The user associated with the bot.

Returns:

The parsed bot object.

Return type:

Bot

parse_bot_oauth2(payload, /)[source]

Parses a bot OAuth2 settings object.

Added in version 1.2.

Parameters:

payload (Dict[str, Any]) – The bot OAuth2 settings payload to parse.

Returns:

The parsed bot OAuth2 settings object.

Return type:

BotOAuth2

parse_bot_user_metadata(payload, /)[source]

Parses a bot user metadata.

Parameters:

  • payload (Dict[str, Any]) – The bot payload to parse.

  • user (raw.User) – The user associated with the bot.

Returns:

The parsed bot user metadata object.

Return type:

BotUserMetadata

parse_bots(payload, /)[source]

Parses an object with bots and associated bot users.

Parameters:

payload (Dict[str, Any]) – The list payload to parse.

Returns:

The parsed bot objects.

Return type:

List[Bot]

parse_bulk_message_delete_event(shard, payload, /)[source]

Parses a BulkMessageDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message bulk delete event object.

Return type:

MessageDeleteBulkEvent

parse_category(payload, /)[source]

Parses a category object.

Parameters:

payload (Dict[str, Any]) – The category payload to parse.

Returns:

The parsed category object.

Return type:

Category

parse_channel_ack_event(shard, payload, /)[source]

Parses a ChannelAck event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message ack event object.

Return type:

MessageAckEvent

parse_channel_create_event(shard, payload, /)[source]

Parses a ChannelCreate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed channel create event object.

Return type:

ChannelCreateEvent

parse_channel_delete_event(shard, payload, /)[source]

Parses a ChannelDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed channel delete event object.

Return type:

ChannelDeleteEvent

parse_channel_group_join_event(shard, payload, /)[source]

Parses a ChannelGroupJoin event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed group recipient add event object.

Return type:

GroupRecipientAddEvent

parse_channel_group_leave_event(shard, payload, /)[source]

Parses a ChannelGroupLeave event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed group recipient remove event object.

Return type:

GroupRecipientRemoveEvent

parse_channel_start_typing_event(shard, payload, /)[source]

Parses a ChannelStartTyping event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed channel typing start event object.

Return type:

ChannelStartTypingEvent

parse_channel_stop_typing_event(shard, payload, /)[source]

Parses a ChannelStopTyping event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed channel typing stop event object.

Return type:

ChannelStopTypingEvent

parse_channel_unread(payload, /)[source]

Parses a channel unread object.

Parameters:

payload (Dict[str, Any]) – The channel unread payload to parse.

Returns:

The parsed channel unread object.

Return type:

ReadState

parse_channel_update_event(shard, payload, /)[source]

Parses a ChannelUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed channel update event object.

Return type:

ChannelUpdateEvent

parse_channel_voice_state(payload, /)[source]

Parses a channel voice state container object.

Parameters:

payload (Dict[str, Any]) – The channel voice state container payload to parse.

Returns:

The parsed channel voice state container object.

Return type:

ChannelVoiceStateContainer

parse_channel(payload, /)[source]

Parses a channel object.

Parameters:

payload (Dict[str, Any]) – The channel payload to parse.

Returns:

The parsed channel object.

Return type:

Channel

parse_created_report(payload, /)[source]

Parses a created report object.

Parameters:

payload (Dict[str, Any]) – The created report payload to parse.

Returns:

The parsed created report object.

Return type:

CreatedReport

parse_detached_emoji(payload, /)[source]

Parses a detached emoji object.

Parameters:

payload (Dict[str, Any]) – The detached emoji payload to parse.

Returns:

The parsed detached emoji object.

Return type:

DetachedEmoji

parse_disabled_response_login(payload, /)[source]

Parses a “Account Disabled” login response object.

Parameters:

payload (Dict[str, Any]) – The login response payload to parse.

Returns:

The parsed “Account Disabled” login response object.

Return type:

AccountDisabled

parse_direct_message_channel(payload, /)[source]

Parses a DM channel object.

Parameters:

payload (Dict[str, Any]) – The DM channel payload to parse.

Returns:

The parsed DM channel object.

Return type:

DMChannel

parse_discoverable_bot(payload, /)[source]

Parses a discoverable bot object.

Parameters:

payload (Dict[str, Any]) – The discoverable bot payload to parse.

Returns:

The parsed bot object.

Return type:

DiscoverableBot

parse_discoverable_bot_search_result(payload, /)[source]

Parses a bot search results object.

Parameters:

payload (Dict[str, Any]) – The bot search results payload to parse.

Returns:

The parsed bot search results object.

Return type:

BotSearchResult

parse_discoverable_bots_page(payload, /)[source]

Parses a discoverable bots page object.

Parameters:

payload (Dict[str, Any]) – The discoverable bots page payload to parse.

Returns:

The parsed discoverable bots page object.

Return type:

DiscoverableBotsPage

parse_discoverable_server(payload, /)[source]

Parses a discoverable server object.

Parameters:

payload (Dict[str, Any]) – The discoverable server payload to parse.

Returns:

The parsed server object.

Return type:

DiscoverableServer

parse_discoverable_servers_page(payload, /)[source]

Parses a discoverable servers page object.

Parameters:

payload (Dict[str, Any]) – The discoverable servers page payload to parse.

Returns:

The parsed discoverable servers page object.

Return type:

DiscoverableServersPage

parse_discoverable_server_search_result(payload, /)[source]

Parses a server search results object.

Parameters:

payload (Dict[str, Any]) – The server search results payload to parse.

Returns:

The parsed server search results object.

Return type:

ServerSearchResult

parse_discoverable_theme(payload, /)[source]

Parses a discoverable theme object.

Parameters:

payload (Dict[str, Any]) – The discoverable theme payload to parse.

Returns:

The parsed theme object.

Return type:

DiscoverableTheme

parse_discoverable_theme_search_result(payload, /)[source]

Parses a theme search results object.

Parameters:

payload (Dict[str, Any]) – The theme search results payload to parse.

Returns:

The parsed theme search results object.

Return type:

ThemeSearchResult

parse_discoverable_themes_page(payload, /)[source]

Parses a discoverable themes page object.

Parameters:

payload (Dict[str, Any]) – The discoverable themes page payload to parse.

Returns:

The parsed discoverable themes page object.

Return type:

DiscoverableThemesPage

parse_display_user(payload, /)[source]

Parses a display user object.

Parameters:

payload (Dict[str, Any]) – The display user payload to parse.

Returns:

The parsed user object.

Return type:

DisplayUser

parse_embed(payload, /)[source]

Parses an embed object.

Parameters:

payload (Dict[str, Any]) – The embed payload to parse.

Returns:

The parsed embed object.

Return type:

Embed

parse_embed_special(payload, /)[source]

Parses an embed special remote content object.

Parameters:

payload (Dict[str, Any]) – The embed special remote content payload to parse.

Returns:

The parsed embed special remote content object.

Return type:

EmbedSpecial

parse_emoji(payload, /)[source]

Parses an emoji object.

Parameters:

payload (Dict[str, Any]) – The emoji payload to parse.

Returns:

The parsed emoji object.

Return type:

Emoji

parse_emoji_create_event(shard, payload, /)[source]

Parses an EmojiCreate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed emoji create event object.

Return type:

EmojiCreateEvent

parse_emoji_delete_event(shard, payload, /)[source]

Parses an EmojiDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server emoji delete event object.

Return type:

ServerEmojiDeleteEvent

parse_gif_embed_special(_, /)[source]

Parses a GIF embed special content object.

Parameters:

payload (Dict[str, Any]) – The GIF embed special content payload to parse.

Returns:

The parsed GIF embed special content object.

Return type:

GIFEmbedSpecial

parse_group_channel(payload, recipients, /)[source]

Parses a group channel object.

Parameters:

  • payload (Dict[str, Any]) – The group channel payload to parse.

  • recipients (Union[Tuple[Literal[True], List[str]], Tuple[Literal[False], List[User]]]) – The group’s recipients.

Returns:

The parsed group channel object.

Return type:

GroupChannel

parse_group_invite(payload, /)[source]

Parses a group invite object.

Parameters:

payload (Dict[str, Any]) – The group invite payload to parse.

Returns:

The parsed group invite object.

Return type:

GroupInvite

parse_group_public_invite(payload, /)[source]

Parses a group public invite object.

Parameters:

payload (Dict[str, Any]) – The group public invite payload to parse.

Returns:

The parsed group public invite object.

Return type:

GroupPublicInvite

parse_image_embed(payload, /)[source]

Parses an image embed object.

Parameters:

payload (Dict[str, Any]) – The image embed payload to parse.

Returns:

The parsed image embed object.

Return type:

ImageEmbed

parse_instance(payload, /)[source]

Parses an instance object.

Parameters:

payload (Dict[str, Any]) – The instance payload to parse.

Returns:

The parsed instance object.

Return type:

Instance

parse_instance_build(payload, /)[source]

Parses an instance build object.

Parameters:

payload (Dict[str, Any]) – The instance build payload to parse.

Returns:

The parsed instance build object.

Return type:

InstanceBuild

parse_instance_captcha_feature(payload, /)[source]

Parses an instance CAPTCHA feature object.

Parameters:

payload (Dict[str, Any]) – The instance CAPTCHA feature payload to parse.

Returns:

The parsed instance CAPTCHA feature object.

Return type:

InstanceCaptchaFeature

parse_instance_features_config(payload, /)[source]

Parses an instance features config object.

Parameters:

payload (Dict[str, Any]) – The instance features config payload to parse.

Returns:

The parsed instance features config object.

Return type:

InstanceFeaturesConfig

parse_instance_generic_feature(payload, /)[source]

Parses an instance generic feature object.

Parameters:

payload (Dict[str, Any]) – The instance generic feature payload to parse.

Returns:

The parsed instance generic feature object.

Return type:

InstanceGenericFeature

parse_instance_voice_feature(payload, livekit, /)[source]

Parses an instance voice feature object.

Parameters:

payload (Dict[str, Any]) – The instance voice feature payload to parse.

Returns:

The parsed instance voice feature object.

Return type:

InstanceVoiceFeature

parse_instance_livekit_voice_node(payload, /)[source]

Parses an instance voice node object.

Parameters:

payload (Dict[str, Any]) – The instance voice node payload to parse.

Returns:

The parsed instance voice node object.

Return type:

InstanceLivekitVoiceNode

parse_invite(payload, /)[source]

Parses an invite object.

Parameters:

payload (Dict[str, Any]) – The invite payload to parse.

Returns:

The parsed invite object.

Return type:

Invite

parse_lightspeed_embed_special(payload, /)[source]

Parses a Lightspeed.tv embed special content object.

Parameters:

payload (Dict[str, Any]) – The Lightspeed.tv embed special content payload to parse.

Returns:

The parsed Lightspeed.tv embed special content object.

Return type:

LightspeedEmbedSpecial

parse_logout_event(shard, payload, /)[source]

Parses a Logout event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed logout event object.

Return type:

LogoutEvent

parse_member(payload, user=None, users={}, /)[source]

Parses a member object.

Parameters:

  • payload (Dict[str, Any]) – The member payload to parse.

  • user (Optional[User]) – The user.

  • users (Dict[str, User]) – The mapping of user IDs to user objects. Required for trying populating Member.user.

Returns:

The parsed member object.

Return type:

Member

parse_member_list(payload, /)[source]

Parses a member list object.

Parameters:

payload (Dict[str, Any]) – The member list payload to parse.

Returns:

The parsed member list object.

Return type:

MemberList

parse_members_with_users(payload, /)[source]

Parses an object with members and associated users.

Parameters:

payload (Dict[str, Any]) – The list payload to parse.

Returns:

The parsed member objects.

Return type:

List[Member]

parse_message(payload, members={}, users={}, cls=<class 'stoat.message.Message'>, /)[source]

Parses a message object.

Parameters:

  • payload (Dict[str, Any]) – The message payload to parse.

  • members (Dict[str, Member]) – The mapping of user IDs to member objects. Required for trying populating Message.author.

  • users (Dict[str, User]) – The mapping of user IDs to user objects. Required for trying populating Message.author.

  • cls (Type[Message]) – The message class to use when constructing final object. The constructor of provided class must be compatible with default one.

Returns:

The parsed message object.

Return type:

Message

parse_message_append_event(shard, payload, /)[source]

Parses a MessageAppend event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message append event object.

Return type:

MessageAppendEvent

parse_message_call_started_system_event(payload, members={}, users={}, /)[source]

Parses a “Call Started” message system event object.

Parameters:
Returns:

The parsed “Call Started” message system event object.

Return type:

StatelessCallStartedSystemEvent

parse_message_channel_description_changed_system_event(payload, members={}, users={}, /)[source]

Parses a “Channel Description Changed” message system event object.

Parameters:
Returns:

The parsed “Channel Description Changed” message system event object.

Return type:

StatelessChannelDescriptionChangedSystemEvent

parse_message_channel_icon_changed_system_event(payload, members={}, users={}, /)[source]

Parses a “Channel Icon Changed” message system event object.

Parameters:
Returns:

The parsed “Channel Icon Changed” message system event object.

Return type:

StatelessChannelIconChangedSystemEvent

parse_message_channel_renamed_system_event(payload, members={}, users={}, /)[source]

Parses a “Channel Renamed” message system event object.

Parameters:
Returns:

The parsed “Channel Renamed” message system event object.

Return type:

StatelessChannelRenamedSystemEvent

parse_message_channel_ownership_changed_system_event(payload, members={}, users={}, /)[source]

Parses a “Channel Ownership Changed” message system event object.

Parameters:
Returns:

The parsed “Channel Ownership Changed” message system event object.

Return type:

StatelessChannelOwnershipChangedSystemEvent

parse_message_delete_event(shard, payload, /)[source]

Parses a MessageDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message delete event object.

Return type:

MessageDeleteEvent

parse_message_event(shard, payload, /)[source]

Parses a Message event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message create event object.

Return type:

MessageCreateEvent

parse_message_interactions(payload, /)[source]

Parses a message interactions object.

Parameters:

payload (Dict[str, Any]) – The message interactions payload to parse.

Returns:

The parsed message interactions object.

Return type:

MessageInteractions

parse_message_masquerade(payload, /)[source]

Parses a message masquerade object.

Parameters:

payload (Dict[str, Any]) – The message masquerade payload to parse.

Returns:

The parsed message masquerade object.

Return type:

MessageMasquerade

parse_message_message_pinned_system_event(payload, members={}, users={}, /)[source]

Parses a “Message Pinned” message system event object.

Parameters:
Returns:

The parsed “Message Pinned” message system event object.

Return type:

StatelessMessagePinnedSystemEvent

parse_message_message_unpinned_system_event(payload, members={}, users={}, /)[source]

Parses a “Message Unpinned” message system event object.

Parameters:
Returns:

The parsed “Message Unpinned” message system event object.

Return type:

StatelessMessageUnpinnedSystemEvent

parse_message_react_event(shard, payload, /)[source]

Parses a MessageReact event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message react event object.

Return type:

MessageReactEvent

parse_message_remove_reaction_event(shard, payload, /)[source]

Parses a MessageRemoveReaction event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message clear reaction event object.

Return type:

MessageClearReactionEvent

parse_message_reported_content(payload, /)[source]

Parses a message reported content object.

Parameters:

payload (Dict[str, Any]) – The message reported content payload to parse.

Returns:

The parsed message reported content object.

Return type:

MessageReportedContent

parse_message_start_edting(shard, payload, /)[source]

Parses a message start editing event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message start editing event object.

Return type:

MessageStartEditingEvent

parse_message_stop_edting(shard, payload, /)[source]

Parses a message stop editing event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message stop editing event object.

Return type:

MessageStopEditingEvent

parse_message_system_event(payload, members, users, /)[source]

Parses a message system event object.

Parameters:

  • payload (Dict[str, Any]) – The message system event payload to parse.

  • members (Dict[str, Member]) – The mapping of user IDs to member objects. Required for trying populating various user-related attributes.

  • users (Dict[str, User]) – The mapping of user IDs to user objects. Required for trying populating various user-related attributes.

Returns:

The parsed message system event object.

Return type:

StatelessSystemEvent

parse_message_text_system_event(payload, members={}, users={}, /)[source]

Parses a text message system event object.

Parameters:
Returns:

The parsed text message system event object.

Return type:

TextSystemEvent

parse_message_unreact_event(shard, payload, /)[source]

Parses a MessageUnreact event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message unreact event object.

Return type:

MessageUnreactEvent

parse_message_update_event(shard, payload, /)[source]

Parses a MessageUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed message update event object.

Return type:

MessageUpdateEvent

parse_message_user_added_system_event(payload, members={}, users={}, /)[source]

Parses a “User Added” message system event object.

Parameters:
Returns:

The parsed “User Added” message system event object.

Return type:

StatelessUserAddedSystemEvent

parse_message_user_banned_system_event(payload, members={}, users={}, /)[source]

Parses a “User Banned” message system event object.

Parameters:
Returns:

The parsed “User Banned” message system event object.

Return type:

StatelessUserBannedSystemEvent

parse_message_user_joined_system_event(payload, members={}, users={}, /)[source]

Parses a “User Joined” message system event object.

Parameters:
Returns:

The parsed “User Joined” message system event object.

Return type:

StatelessUserJoinedSystemEvent

parse_message_user_kicked_system_event(payload, members={}, users={}, /)[source]

Parses a “User Kicked” message system event object.

Parameters:
Returns:

The parsed “User Kicked” message system event object.

Return type:

StatelessUserKickedSystemEvent

parse_message_user_left_system_event(payload, members={}, users={}, /)[source]

Parses a “User Left” message system event object.

Parameters:
Returns:

The parsed “User Left” message system event object.

Return type:

StatelessUserLeftSystemEvent

parse_message_user_remove_system_event(payload, members={}, users={}, /)[source]

Parses a “User Removed” message system event object.

Parameters:
Returns:

The parsed “User Removed” message system event object.

Return type:

StatelessUserRemovedSystemEvent

parse_message_webhook(payload, /)[source]

Parses a message webhook object.

Parameters:

payload (Dict[str, Any]) – The message webhook payload to parse.

Returns:

The parsed message webhook object.

Return type:

MessageWebhook

parse_messages(payload, /)[source]

Parses an object with messages and associated users/members.

Parameters:

payload (Dict[str, Any]) – The list payload to parse.

Returns:

The parsed message objects.

Return type:

List[Message]

parse_mfa_response_login(payload, friendly_name, /)[source]

Parses a “MFA required” login response object.

Parameters:

  • payload (Dict[str, Any]) – The login response payload to parse.

  • friendly_name (Optional[str]) – The user-friendly name of client.

Returns:

The parsed “MFA required” login response object.

Return type:

MFARequired

parse_mfa_ticket(payload, /)[source]

Parses a MFA ticket object.

Parameters:

payload (Dict[str, Any]) – The MFA ticket payload to parse.

Returns:

The parsed MFA ticket object.

Return type:

MFATicket

parse_multi_factor_status(payload, /)[source]

Parses a MFA status object.

Parameters:

payload (Dict[str, Any]) – The MFA status payload to parse.

Returns:

The parsed MFA status object.

Return type:

MFAStatus

parse_mutuals(payload, /)[source]

Parses a mutual response object.

Parameters:

payload (Dict[str, Any]) – The mutual response payload to parse.

Returns:

The parsed mutual response object.

Return type:

Mutuals

parse_none_embed(_, /)[source]

Parses an empty embed object.

Parameters:

payload (Dict[str, Any]) – The empty embed payload to parse.

Returns:

The parsed empty embed object.

Return type:

NoneEmbed

parse_none_embed_special(_, /)[source]

Parses an empty embed special content object.

Parameters:

payload (Dict[str, Any]) – The empty embed special content payload to parse.

Returns:

The parsed empty embed special content object.

Return type:

NoneEmbedSpecial

parse_oauth2_access_token(payload, /)[source]

Parses an OAuth2 access token object.

Added in version 1.2.

Parameters:

payload (Dict[str, Any]) – The OAuth2 access token payload to parse.

Returns:

The parsed OAuth2 access token.

Return type:

OAuth2AccessToken

parse_oauth2_authorization(payload, /)[source]

Parses an OAuth2 authorization object.

Added in version 1.2.

Parameters:

payload (Dict[str, Any]) – The OAuth2 authorization payload to parse.

Returns:

The parsed OAuth2 authorization.

Return type:

OAuth2Authorization

parse_oauth2_scope_reasoning(payload, /)[source]

Parses an OAuth2 scope reasoning object.

Added in version 1.2.

Parameters:

payload (Dict[str, Any]) – The OAuth2 scope reasoning payload to parse.

Returns:

The parsed OAuth2 scope reasoning.

Return type:

OAuth2ScopeReasoning

parse_own_user(payload, /)[source]

Parses an own user object.

Parameters:

payload (Dict[str, Any]) – The own user payload to parse.

Returns:

The parsed user object.

Return type:

OwnUser

parse_partial_account(payload, /)[source]

Parses a partial account object.

Parameters:

payload (Dict[str, Any]) – The partial account payload to parse.

Returns:

The parsed partial account object.

Return type:

PartialAccount

parse_partial_session(payload, /)[source]

Parses a partial session object.

Parameters:

payload (Dict[str, Any]) – The partial session payload to parse.

Returns:

The parsed partial session object.

Return type:

PartialSession

parse_partial_user_profile(payload, clear, /)[source]

Parses a partial user profile object.

Parameters:

  • payload (Dict[str, Any]) – The partial user profile payload to parse.

  • clear (List[raw.FieldsUser]) – The fields that were cleared.

Returns:

The parsed partial user profile object.

Return type:

PartialUserProfile

parse_permission_override(payload, /)[source]

Parses a permission override object.

Parameters:

payload (Dict[str, Any]) – The permission override payload to parse.

Returns:

The parsed permission override object.

Return type:

PermissionOverride

parse_permission_override_field(payload, /)[source]

Parses a permission override field object.

Parameters:

payload (Dict[str, Any]) – The permission override field payload to parse.

Returns:

The parsed permission override object.

Return type:

PermissionOverride

parse_policy_change(payload, /)[source]

Parses a policy change object.

Parameters:

payload (Dict[str, Any]) – The policy change payload to parse.

Returns:

The parsed policy change object.

Return type:

PolicyChange

parse_possible_oauth2_authorization(payload, /)[source]

Parses a possible OAuth2 authorization object.

Added in version 1.2.

Parameters:

payload (Dict[str, Any]) – The possible OAuth2 authorization payload to parse.

Returns:

The parsed possible OAuth2 authorization.

Return type:

PossibleOAuth2Authorization

parse_public_bot(payload, /)[source]

Parses a public bot object.

Parameters:

payload (Dict[str, Any]) – The public bot payload to parse.

Returns:

The parsed public bot object.

Return type:

PublicBot

parse_public_invite(payload, /)[source]

Parses a public invite object.

Parameters:

payload (Dict[str, Any]) – The public invite payload to parse.

Returns:

The parsed public invite object.

Return type:

PublicInvite

parse_ready_event(shard, payload, /)[source]

Parses a Ready event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed ready event object.

Return type:

ReadyEvent

parse_rejected_report(payload, /)[source]

Parses a rejected report object.

Parameters:

payload (Dict[str, Any]) – The rejected report payload to parse.

Returns:

The parsed rejected report object.

Return type:

RejectedReport

parse_relationship(payload, /)[source]

Parses a relationship object.

Parameters:

payload (Dict[str, Any]) – The relationship payload to parse.

Returns:

The parsed relationship object.

Return type:

Relationship

parse_report(payload, /)[source]

Parses a report object.

Parameters:

payload (Dict[str, Any]) – The report payload to parse.

Returns:

The parsed report object.

Return type:

Report

parse_report_create_event(shard, payload, /)[source]

Parses a ReportCreate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed report create event object.

Return type:

ReportCreateEvent

parse_reported_content(payload, /)[source]

Parses a reported content object.

Parameters:

payload (Dict[str, Any]) – The reported content payload to parse.

Returns:

The parsed reported content object.

Return type:

ReportedContent

parse_resolved_report(payload, /)[source]

Parses a resolved report object.

Parameters:

payload (Dict[str, Any]) – The resolved report payload to parse.

Returns:

The parsed resolved report object.

Return type:

ResolvedReport

parse_response_login(payload, friendly_name, /)[source]

Parses a login response object.

Parameters:

  • payload (Dict[str, Any]) – The login response payload to parse.

  • friendly_name (Optional[str]) – The user-friendly name of client.

Returns:

The parsed login response object.

Return type:

LoginResult

parse_response_webhook(payload, /)[source]

Parses a “webhook as response” object.

Parameters:

payload (Dict[str, Any]) – The webhook payload to parse.

Returns:

The parsed webhook object.

Return type:

Webhook

parse_role(payload, role_id, server_id, /)[source]

Parses a role object.

Parameters:

  • payload (Dict[str, Any]) – The role payload to parse.

  • role_id (str) – The role’s ID.

  • server_id (str) – The server’s ID the role belongs to.

Returns:

The parsed role object.

Return type:

Role

parse_saved_messages_channel(payload, /)[source]

Parses a saved messages channel object.

Parameters:

payload (Dict[str, Any]) – The saved messages channel payload to parse.

Returns:

The parsed saved messages channel object.

Return type:

SavedMessagesChannel

parse_server(payload, channels, /)[source]

Parses a server object.

Parameters:

  • payload (Dict[str, Any]) – The server payload to parse.

  • channels (Union[Tuple[Literal[True], List[str]], Tuple[Literal[False], List[raw.ServerChannel]]]) – The server’s channels.

Returns:

The parsed server object.

Return type:

Server

parse_server_create_event(shard, payload, joined_at, /)[source]

Parses a server create event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server create event object.

Return type:

ServerCreateEvent

parse_server_delete_event(shard, payload, /)[source]

Parses a server delete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server delete event object.

Return type:

ServerDeleteEvent

parse_server_emoji(payload, /)[source]

Parses a server emoji object.

Parameters:

payload (Dict[str, Any]) – The server emoji payload to parse.

Returns:

The parsed server emoji object.

Return type:

ServerEmoji

parse_server_invite(payload, /)[source]

Parses a server private invite object.

Parameters:

payload (Dict[str, Any]) – The server private invite payload to parse.

Returns:

The parsed server private invite object.

Return type:

ServerPrivateInvite

parse_server_member_join_event(shard, payload, joined_at, /)[source]

Parses a server member join event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server member join event object.

Return type:

ServerMemberJoinEvent

parse_server_member_leave_event(shard, payload, /)[source]

Parses a server member remove event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server member remove event object.

Return type:

ServerMemberRemoveEvent

parse_server_member_update_event(shard, payload, /)[source]

Parses a server member update event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server member update event object.

Return type:

ServerMemberUpdateEvent

parse_server_public_invite(payload, /)[source]

Parses a server public invite object.

Parameters:

payload (Dict[str, Any]) – The server public invite payload to parse.

Returns:

The parsed server public invite object.

Return type:

ServerPublicInvite

parse_server_reported_content(payload, /)[source]

Parses a server reported content object.

Parameters:

payload (Dict[str, Any]) – The server reported content payload to parse.

Returns:

The parsed server reported content object.

Return type:

ServerReportedContent

parse_server_role_delete_event(shard, payload, /)[source]

Parses a ServerRoleDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server role delete event object.

Return type:

ServerRoleDeleteEvent

parse_server_role_ranks_update_event(shard, payload, /)[source]

Parses a ServerRoleRanksUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server role ranks update event object.

Return type:

ServerRoleRanksUpdateEvent

parse_server_role_update_event(shard, payload, /)[source]

Parses a ServerRoleUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server role create/update event object.

Return type:

RawServerRoleUpdateEvent

parse_server_update_event(shard, payload, /)[source]

Parses a ServerUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed server update event object.

Return type:

ServerUpdateEvent

parse_session(payload, /)[source]

Parses a session object.

Parameters:

payload (Dict[str, Any]) – The session payload to parse.

Returns:

The parsed session object.

Return type:

Session

parse_soundcloud_embed_special(_, /)[source]

Parses a Soundcloud embed special content object.

Parameters:

payload (Dict[str, Any]) – The Soundcloud embed special content payload to parse.

Returns:

The parsed Soundcloud embed special content object.

Return type:

SoundcloudEmbedSpecial

parse_spotify_embed_special(payload, /)[source]

Parses a Spotify embed special content object.

Parameters:

payload (Dict[str, Any]) – The Spotify embed special content payload to parse.

Returns:

The parsed Spotify embed special content object.

Return type:

SpotifyEmbedSpecial

parse_streamable_embed_special(payload, /)[source]

Parses a Streamable embed special content object.

Parameters:

payload (Dict[str, Any]) – The Streamable embed special content payload to parse.

Returns:

The parsed Streamable embed special content object.

Return type:

StreamableEmbedSpecial

parse_system_message_channels(payload, /)[source]

Parses a system message channels object.

Parameters:

payload (Dict[str, Any]) – The system message channels payload to parse.

Returns:

The parsed system message channels object.

Return type:

SystemMessageChannels

parse_text_channel(payload, /)[source]

Parses a text channel object.

Parameters:

payload (Dict[str, Any]) – The text channel payload to parse.

Returns:

The parsed text channel object.

Return type:

TextChannel

parse_text_embed(payload, /)[source]

Parses a text embed object.

Parameters:

payload (Dict[str, Any]) – The text embed payload to parse.

Returns:

The parsed text embed object.

Return type:

TextEmbed

parse_twitch_embed_special(payload, /)[source]

Parses a Twitch embed special content object.

Parameters:

payload (Dict[str, Any]) – The Twitch embed special content payload to parse.

Returns:

The parsed Twitch embed special content object.

Return type:

TwitchEmbedSpecial

parse_unknown_public_invite(payload, /)[source]

Parses an unknown public invite object.

Parameters:

payload (Dict[str, Any]) – The unknown public invite payload to parse.

Returns:

The parsed unknown public invite object.

Return type:

UnknownPublicInvite

parse_user(payload, /)[source]

Parses an user object.

Parameters:

payload (Dict[str, Any]) – The user payload to parse.

Returns:

The parsed user object.

Return type:

Union[User, OwnUser]

parse_user_move_voice_channel_event(shard, payload, /)[source]

Parses an UserMoveVoiceChannel event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user move voice channel event object.

Return type:

UserMoveVoiceChannelEvent

parse_user_platform_wipe_event(shard, payload, /)[source]

Parses an UserPlatformWipe event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user platform wipe event object.

Return type:

UserPlatformWipeEvent

parse_user_profile(payload, /)[source]

Parses an user profile object.

Parameters:

payload (Dict[str, Any]) – The user profile payload to parse.

Returns:

The parsed user profile object.

Return type:

UserProfile

parse_user_relationship_event(shard, payload, /)[source]

Parses an UserRelationship event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user relationship event object.

Return type:

UserRelationshipUpdateEvent

parse_user_reported_content(payload, /)[source]

Parses an user reported content object.

Parameters:

payload (Dict[str, Any]) – The user reported content payload to parse.

Returns:

The parsed user reported content object.

Return type:

UserReportedContent

parse_user_settings(payload, partial, /)[source]

Parses a nuser settings object.

Parameters:

  • payload (Dict[str, Any]) – The user settings payload to parse.

  • partial (bool) – Whether the user settings are partial.

Returns:

The parsed user settings object.

Return type:

UserSettings

parse_user_settings_update_event(shard, payload, /)[source]

Parses an UserSettingsUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user settings update event object.

Return type:

UserSettingsUpdateEvent

parse_user_status(payload, /)[source]

Parses an user status object.

Parameters:

payload (Dict[str, Any]) – The user status payload to parse.

Returns:

The parsed user status object.

Return type:

UserStatus

parse_user_status_edit(payload, clear, /)[source]

Parses an user status edit object.

Parameters:

  • payload (Dict[str, Any]) – The user status payload to parse.

  • clear (List[raw.FieldsUser]) – The fields that were cleared.

Returns:

The parsed user status edit object.

Return type:

UserStatusEdit

parse_user_update_event(shard, payload, /)[source]

Parses an UserUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user update event object.

Return type:

UserUpdateEvent

parse_user_voice_state(payload, /)[source]

Parses an user voice state object.

Parameters:

payload (Dict[str, Any]) – The user voice state payload to parse.

Returns:

The parsed user voice state object.

Return type:

UserVoiceState

parse_user_voice_state_update_event(shard, payload, /)[source]

Parses an user voice state update event.

Parameters:

payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed user voice state update object.

Return type:

UserVoiceStateUpdateEvent

parse_video_embed(payload, /)[source]

Parses a video embed object.

Parameters:

payload (Dict[str, Any]) – The video embed payload to parse.

Returns:

The parsed video embed object.

Return type:

VideoEmbed

parse_voice_channel(payload, /)[source]

Parses a voice channel object.

Deprecated since version 0.7.0: The method was deprecated in favour of parse_text_channel() and using TextChannel.voice instead.

Parameters:

payload (Dict[str, Any]) – The voice channel payload to parse.

Returns:

The parsed voice channel object.

Return type:

VoiceChannel

parse_voice_channel_join_event(shard, payload, /)[source]

Parses a voice channel join event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed voice channel join event object.

Return type:

VoiceChannelJoinEvent

parse_voice_channel_leave_event(shard, payload, /)[source]

Parses a voice channel leave event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed voice channel leave event object.

Return type:

VoiceChannelLeaveEvent

parse_voice_channel_move_event(shard, payload, /)[source]

Parses a voice channel move event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed voice channel move event object.

Return type:

VoiceChannelMoveEvent

parse_voice_information(payload, /)[source]

Parses a channel voice metadata object.

Parameters:

payload (Dict[str, Any]) – The channel voice metadata payload to parse.

Returns:

The parsed channel voice metadata object.

Return type:

ChannelVoiceMetadata

parse_webhook(payload, /)[source]

Parses a webhook object.

Parameters:

payload (Dict[str, Any]) – The webhook payload to parse.

Returns:

The parsed webhook object.

Return type:

Webhook

parse_webhook_create_event(shard, payload, /)[source]

Parses a WebhookCreate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed webhook create event object.

Return type:

WebhookCreateEvent

parse_webhook_update_event(shard, payload, /)[source]

Parses a WebhookUpdate event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed webhook update event object.

Return type:

WebhookUpdateEvent

parse_webhook_delete_event(shard, payload, /)[source]

Parses a WebhookDelete event.

Parameters:

  • shard (Shard) – The shard the event arrived on.

  • payload (Dict[str, Any]) – The event payload to parse.

Returns:

The parsed webhook delete event object.

Return type:

WebhookDeleteEvent

parse_webpush_subscription(payload, /)[source]

Parses a WebPush subscription object.

Parameters:

payload (Dict[str, Any]) – The WebPush subscription payload to parse.

Returns:

The parsed WebPush subscription object.

Return type:

WebPushSubscription

parse_website_embed(payload, /)[source]

Parses a website embed object.

Parameters:

payload (Dict[str, Any]) – The website embed payload to parse.

Returns:

The parsed website embed object.

Return type:

WebsiteEmbed

parse_youtube_embed_special(payload)[source]

Parses a YouTube embed special content object.

Parameters:

payload (Dict[str, Any]) – The YouTube embed special content payload to parse.

Returns:

The parsed YouTube embed special content object.

Return type:

YouTubeEmbedSpecial

Permissions Calculator

stoat.calculate_saved_messages_channel_permissions(perspective_id, user_id, /)[source]

Calculates the permissions in SavedMessagesChannel scope.

Parameters:

  • perspective_id (str) – The ID of perspective user.

  • user_id (str) – The ID of channel owner (SavedMessagesChannel.owner_id).

Returns:

The calculated permissions.

Return type:

Permissions

stoat.calculate_dm_channel_permissions(permissions, /)[source]

Calculates the permissions in DMChannel scope.

Parameters:

permissions (UserPermissions) – The user permissions.

Returns:

The calculated permissions.

Return type:

Permissions

stoat.calculate_group_channel_permissions(perspective_id, /, *, group_owner_id, group_permissions, group_recipients)[source]

Calculates the permissions in GroupChannel scope.

Parameters:
Returns:

The calculated permissions.

Return type:

Permissions

stoat.calculate_server_channel_permissions(initial_permissions, roles, *, default_permissions, role_permissions)[source]

Calculates the permissions in BaseServerChannel scope.

Parameters:
Returns:

The calculated permissions.

Return type:

Permissions

stoat.calculate_server_permissions(target_roles, target_timeout, /, *, default_permissions, can_publish=True, can_receive=True, category=None)[source]

Calculates the permissions in Server scope.

Parameters:

  • target_roles (List[Role]) – The target member’s roles. Should be empty list if calculating against User, or stoat.sort_member_roles(member.roles, server_roles=server.roles) if calculating against member.

  • target_timeout (Optional[datetime]) – The target timeout, if applicable (Member.timed_out_until).

  • default_permissions (Permissions) – The default channel permissions (Server.default_permissions).

  • can_publish (bool) – Whether the member can send voice data. Defaults to True.

  • can_receive (bool) – Whether the member can receive voice data. Defaults to True.

  • category (Optional[Category]) –

    The category to calculate permissions with.

    Added in version 1.2.

Returns:

The calculated permissions.

Return type:

Permissions

stoat.calculate_user_permissions(user_id, user_relationship, user_bot, /, *, perspective_id, perspective_bot, perspective_privileged)[source]

Calculates the permissions between two users.

Parameters:
Returns:

The calculated permissions.

Return type:

UserPermissions

Utility Functions

stoat.ulid_new(*, timestamp=None, randomness=None)[source]

str: Generate an ULID.

Parameters:

  • timestamp (Optional[float]) – The UNIX timestamp. Defaults to current time.

  • randomness (Optional[bytes]) – The randomness. Must be exactly 10 bytes. Defaults to urandom().

stoat.ulid_timestamp(val, /)[source]

Returns timestamp for specified ULID.

Parameters:

val (str) – The ID to get timestamp from.

Returns:

The UNIX timestamp.

Return type:

float

stoat.ulid_time(val, /)[source]

Returns timestamp for specified ULID.

Parameters:

val (str) – The ID to get timestamp from.

Returns:

The timestamp.

Return type:

datetime

stoat.sort_member_roles(target_role_ids, /, *, safe=True, server_roles)[source]

Sorts the member roles.

Parameters:

  • target_role_ids (List[str]) – The IDs of roles to sort (Member.role_ids).

  • safe (bool) – Whether to raise exception or not if role is missing in cache.

  • server_roles (Dict[str, Role]) – The mapping of role IDs to role objects (Server.roles).

Raises:

NoData – The role is not found in cache.

Returns:

The sorted result, in ascending order.

Return type:

List[Role]

Abstract Base Classes

Messageable

Attributes
Methods
class stoat.abc.Messageable[source]

An ABC that allows derived instances to send messages.

The following classes implement this ABC:

async with typing()[source]

Returns an asynchronous context manager that allows you to send a typing indicator in destination channel for an indefinite period of time.

await fetch_channel_id(*, http_overrides=None)[source]

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:

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

Returns:

The channel’s ID.

Return type:

str

get_channel_id()[source]

str: Retrieves the channel’s ID, if possible.

get_message(message_id, /)[source]

Retrieves a channel message from cache.

Parameters:

message_id (str) – The message ID.

Returns:

The message or None if not found.

Return type:

Optional[Message]

property messages[source]

Returns all messages in this channel.

Type:

Mapping[str, Message]

await begin_typing(*, http_overrides=None)[source]

Begins typing in channel, until end_typing() is called.

await end_typing(*, http_overrides=None)[source]

Ends typing in channel.

await acknowledge(message=UNDEFINED, *, channel_http_overrides=None, http_overrides=None)[source]

This function is a coroutine.

Marks the destination channel as read.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

  • message (ULIDOr[BaseMessage]) – The message to mark as read.

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    IsBot

    The current token belongs to bot account.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to view the channel.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.
await fetch_message(message, /, *, channel_http_overrides=None, http_overrides=None)[source]

This function is a coroutine.

Retrieves a message.

Parameters:

  • message (ULIDOr[BaseMessage]) – The message to retrieve.

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

Raises:

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to view the channel.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel/message was not found.

  • InternalServerError – Possible values for type:

Returns:

The retrieved message.

Return type:

Message

await history(*, channel_http_overrides=None, http_overrides=None, limit=None, before=None, after=None, sort=None, nearby=None, populate_users=None)[source]

This function is a coroutine.

Retrieve message history from destination channel.

You must have read_message_history to do this.

Parameters:

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

  • limit (Optional[int]) –

    The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

    If nearby is provided, then this is (limit + 2).

  • before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.

  • after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.

  • sort (Optional[MessageSort]) – The message sort direction. Defaults to latest

  • nearby (Optional[ULIDOr[BaseMessage]]) –

    The message to search around.

    Providing this parameter will discard before, after and sort parameters.

    It will also take half of limit rounded as the limits to each side. It also fetches the message specified.

  • populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to read the message history.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    collection, operation
Returns:

The messages retrieved.

Return type:

List[Message]

await search(query=None, *, channel_http_overrides=None, http_overrides=None, pinned=None, limit=None, before=None, after=None, sort=None, populate_users=None)[source]

This function is a coroutine.

Searches for messages in destination channel.

For query and pinned, only one parameter can be provided, otherwise a HTTPException will be thrown with InvalidOperation type.

You must have read_message_history to do this.

Note

This can only be used by non-bot accounts.

Parameters:

  • query (Optional[str]) – The full-text search query. See MongoDB documentation for more information.

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

  • pinned (Optional[bool]) – Whether to search for (un-)pinned messages or not.

  • limit (Optional[int]) –

    The maximum number of messages to get. Must be between 1 and 100. Defaults to 50.

    If nearby is provided, then this is (limit + 2).

  • before (Optional[ULIDOr[BaseMessage]]) – The message before which messages should be fetched.

  • after (Optional[ULIDOr[BaseMessage]]) – The message after which messages should be fetched.

  • sort (Optional[MessageSort]) – The message sort direction. Defaults to latest

  • nearby (Optional[ULIDOr[BaseMessage]]) –

    The message to search around.

    Providing this parameter will discard before, after and sort parameters.

    It will also take half of limit rounded as the limits to each side. It also fetches the message specified.

  • populate_users (bool) – Whether to populate user (and member, if server channel) objects.

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    FailedValidation

    One of before, after or nearby parameters were invalid IDs.

    InvalidOperation

    You provided both query and pinned parameters.

    IsBot

    The current token belongs to bot account.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to search messages.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    collection, operation
Returns:

The messages matched.

Return type:

List[Message]

await send(content=None, *, channel_http_overrides=None, http_overrides=None, nonce=None, attachments=None, replies=None, embeds=None, masquerade=None, interactions=None, silent=None, mention_everyone=None, mention_online=None)[source]

This function is a coroutine.

Sends a message to destination channel.

You must have send_messages to do this.

If message mentions “@everyone” or “@online”, you must have mention_everyone to do that.

If message mentions any roles, you must mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see destination channel.

Parameters:

  • content (Optional[str]) – The message content.

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

  • nonce (Optional[str]) – The message nonce.

  • attachments (Optional[List[ResolvableResource]]) –

    The attachments to send the message with.

    You must have upload_files to provide this.

  • replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.

  • embeds (Optional[List[SendableEmbed]]) –

    The embeds to send the message with.

    You must have send_embeds to provide this.

  • masquerade (Optional[MessageMasquerade]) –

    The message masquerade.

    You must have use_masquerade to provide this.

    If color is provided, use_masquerade is also required.

  • interactions (Optional[MessageInteractions]) –

    The message interactions.

    If reactions is provided, react is required.

  • silent (Optional[bool]) – Whether to suppress notifications or not.

  • mention_everyone (Optional[bool]) –

    Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.

    Note

    User accounts cannot set this to True.

  • mention_online (Optional[bool]) –

    Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

    Note

    User accounts cannot set this to True.

Raises:

  • stoat.HTTPException – Possible values for type:

    Value

    Reason

    EmptyMessage

    The message was empty.

    FailedValidation

    The payload was invalid.

    InvalidFlagValue

    Both mention_everyone and mention_online were True.

    InvalidOperation

    The passed nonce was already used. One of reactions elements was invalid.

    InvalidProperty

    restrict_reactions was True but reactions was empty.

    IsBot

    The current token belongs to bot account.

    IsNotBot

    The current token belongs to user account.

    PayloadTooLarge

    The message was too large.

    TooManyAttachments

    You provided more attachments than allowed on this instance.

    TooManyEmbeds

    You provided more embeds than allowed on this instance.

    TooManyReplies

    You were replying to more messages than was allowed on this instance.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to send messages.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel/file/reply was not found.

  • stoat.InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    collection, operation

    InternalError

    Somehow something went wrong during message creation.
Returns:

The message that was sent.

Return type:

Message

Connectable

Methods
class stoat.abc.Connectable[source]

An ABC that allows derived instances to connect to voice call.

The following classes implement this ABC:

await fetch_channel_id(*, http_overrides=None)[source]

This function is a coroutine.

Retrieves the channel’s ID.

Parameters:

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

Returns:

The channel’s ID.

Return type:

str

get_channel_id()[source]

str: Retrieves the channel’s ID, if possible.

await join_call(*, channel_http_overrides=None, http_overrides=None, node=UNDEFINED, force_disconnect=UNDEFINED, recipients=UNDEFINED)[source]

This function is a coroutine.

Asks the voice server for a token to join the call in destination channel.

You must have connect to do this.

For Livekit instances, fires MessageCreateEvent and VoiceChannelJoinEvent / VoiceChannelMoveEvent for all users who can see target channel.

Parameters:

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

  • node (UndefinedOr[Optional[str]]) –

    The node’s name to use for starting a call.

    If None or UNDEFINED, the currently assigned channel node will be used.

    If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

    Added in version 1.2.

  • force_disconnect (UndefinedOr[Optional[bool]]) –

    Whether to force disconnect any other existing voice connections. Useful for disconnecting on another device and joining on a new.

    Added in version 1.2.

  • recipients (UndefinedOr[Optional[List[ULIDOr[BaseUser]]]]) –

    A list of users which should be notified of the call starting. Only used when the user is the first one connected.

    Added in version 1.2.

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    AlreadyConnected

    The current user was already connected to this voice channel.

    CannotJoinCall

    The channel was type of saved_messages (or if instance uses legacy voice server, text).

    InvalidOperation

    The voice server is unavailable.

    LivekitUnavailable

    The voice server is unavailable. Only applicable to instances using Livekit.

    NotConnected

    The current user was already connected to other voice channel.

    NotAVoiceChannel

    The channel was not a voice channel. Only applicable to instances using Livekit.

    UnknownNode

    The server could not discover a voice node.

    VosoUnavailable

    The voice server is unavailable. Not applicable to instances using Livekit.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to join a call.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    collection, operation

    InternalError

    Somehow something went during retrieving token.
Returns:

The token for authenticating with the voice server, and node WebSocket URL (can be empty if instance does not use Livekit).

Return type:

Tuple[str, str]

await connect(*, channel_http_overrides=None, http_overrides=None, node=None)[source]

Connects to a destination voice channel and returns a Room associated with destination.

Parameters:

  • channel_http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides for getting channel.

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

  • node (Optional[str]) –

    The node’s name to use for starting a call.

    If None, the currently assigned channel node will be used.

    If channel has no node assigned, you should discover existing voice nodes via query_node() (on official instances, you generally currently should use worldwide). Otherwise, this will throw an UnknownNode error.

    Added in version 1.2.

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    AlreadyConnected

    The current user was already connected to this voice channel.

    CannotJoinCall

    The channel was type of saved_messages (or if instance uses legacy voice server, text).

    InvalidOperation

    The voice server is unavailable.

    LivekitUnavailable

    The voice server is unavailable. Only applicable to instances using Livekit.

    NotConnected

    The current user was already connected to other voice channel.

    NotAVoiceChannel

    The channel was not a voice channel. Only applicable to instances using Livekit.

    UnknownNode

    The server could not discover a voice node.

    VosoUnavailable

    The voice server is unavailable. Not applicable to instances using Livekit.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to join a call.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    collection, operation

    InternalError

    Somehow something went during retrieving token.

  • TypeError – If livekit dependency is not installed.

Models

UndefinedOr

class stoat.UndefinedOr

A generic union of either UNDEFINED or a T.

stoat.UNDEFINED

A type-sentinel to mark something as undefined. Used to distinguish missing parameter from explicit None values.

StatelessAsset

Attributes
Methods
class stoat.StatelessAsset(*, id, filename, metadata, content_type, size, deleted, reported, message_id, user_id, server_id, object_id)[source]

Represents a stateless file on Stoat generated by Autumn.

For better user experience, prefer using parent.foo rather than parent.internal_foo.

id

The asset’s ID.

Type:

str

filename

The asset’s original filename.

Type:

str

metadata

Parsed metadata of this file.

Type:

AssetMetadata

content_type

str The asset’s content type.

size

The asset’s size, in bytes.

Type:

int

deleted

Whether the file was deleted.

Type:

bool

reported

Whether the file was reported.

Type:

bool

message_id

The message’s ID the asset is associated with.

Type:

Optional[str]

user_id

The user’s ID the asset is associated with.

Type:

Optional[str]

server_id

The server’s ID the asset is associated with.

Type:

Optional[str]

object_id

The object’s ID the asset is associated with.

Type:

Optional[str]

attach_state(state, tag, /)[source]

Asset: Attach a state to asset.

Parameters:

  • state (State) – The state to attach.

  • tag (Tag) – The asset’s tag.

to_dict(tag, /)[source]

dict: Convert asset to raw data.

Parameters:

tag (Tag) – The asset tag.

Asset

Attributes
Methods
class stoat.Asset(*, id, filename, metadata, content_type, size, deleted, reported, message_id, user_id, server_id, object_id, state, tag)[source]

Bases: StatelessAsset

Represents an asset on Stoat.

This inherits from StatelessAsset.

url()[source]

str: The asset URL.

await preview()[source]

This function is a coroutine.

Preview an asset. Only applicable for images.

Returns:

The preview in webp format.

Return type:

bytes

await read()[source]

This function is a coroutine.

Read asset contents.

Returns:

The asset contents.

Return type:

bytes

attach_state(state, tag, /)[source]

Asset: Attach a state to asset.

Parameters:

  • state (State) – The state to attach.

  • tag (Tag) – The asset’s tag.

content_type

str The asset’s content type.

deleted

Whether the file was deleted.

Type:

bool

filename

The asset’s original filename.

Type:

str

id

The asset’s ID.

Type:

str

message_id

The message’s ID the asset is associated with.

Type:

Optional[str]

metadata

Parsed metadata of this file.

Type:

AssetMetadata

object_id

The object’s ID the asset is associated with.

Type:

Optional[str]

reported

Whether the file was reported.

Type:

bool

server_id

The server’s ID the asset is associated with.

Type:

Optional[str]

size

The asset’s size, in bytes.

Type:

int

to_dict(tag, /)[source]

dict: Convert asset to raw data.

Parameters:

tag (Tag) – The asset tag.

user_id

The user’s ID the asset is associated with.

Type:

Optional[str]

Attributes
Methods
class stoat.AssetMetadata(*, type, width, height)[source]

Represents metadata associated with an asset.

type

The metadata’s type.

Type:

AssetMetadataType

width

The image/video’s width, if applicable.

Type:

Optional[int]

height

The image/video’s height, if applicable.

Type:

Optional[int]

to_dict()[source]

dict: Convert metadata to raw data.

PermissionOverride

Attributes
Methods
class stoat.PermissionOverride(*, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]

Represents a single permission override.

raw_allow

The raw value of permissions to allow.

Type:

int

raw_deny

The raw value of permissions to deny.

Type:

int

property allow[source]

The permissions to allow.

Type:

Permissions

property deny[source]

The permissions to deny.

Type:

Permissions

to_dict()[source]

dict: Convert override to raw data.

to_field_dict()[source]

dict: Convert override to raw data.

ReadState

Attributes
Methods
class stoat.ReadState(*, state, channel_id, user_id, last_acked_id, mentioned_in)[source]

Represents the read state of a channel.

Note

An entity currently refers to message here. However this might change in future.

channel_id

The channel’s ID the read state for.

Type:

str

user_id

The user’s ID the read state belongs to.

Type:

str

last_acked_id

The last acknowledged entity’s ID. It may not point to an existing or valid entity.

Type:

Optional[str]

mentioned_in

The message’s IDs that mention the user.

Type:

List[str]

get_channel()[source]

Optional[Channel]: The channel the read state belongs to.

property channel[source]

The channel the read state belongs to.

Type:

Channel

await edit(*, last_acked_id=UNDEFINED, http_overrides=None)[source]

This function is a coroutine.

Edits the read state.

You must have view_channel to do this.

Fires MessageAckEvent for the current user.

Note

This can only be used by non-bot accounts.

Parameters:

  • last_acked_id (UndefinedOr[Optional[ULIDOr[BaseMessage]]]) – The new last acknowledged entity’s ID.

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

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    IsBot

    The current token belongs to bot account.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current bot/user token is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    MissingPermission

    You do not have the proper permissions to view the message.

  • NotFound – Possible values for type:

    Value

    Reason

    NotFound

    The channel was not found.
Returns:

The newly updated read state.

Return type:

ReadState

to_dict()[source]

dict: Convert read state to raw data.

InstanceCaptchaFeature

Attributes
class stoat.InstanceCaptchaFeature(*, enabled, key)[source]

Configuration for hCaptcha on Stoat instance.

enabled

Whether the CAPTCHA is enabled on current instance.

Type:

bool

key

The client key used for solving CAPTCHA.

Type:

str

InstanceGenericFeature

Attributes
class stoat.InstanceGenericFeature(*, enabled, url)[source]

Represents how one of Stoat instance services is configured.

enabled

Whether the service is enabled on current instance.

Type:

bool

url

The URL pointing to the service.

Type:

str

InstanceVoiceFeature

stoat.InstanceVoiceFeature

alias of InstanceVosoVoiceFeature | InstanceLivekitVoiceFeature

InstanceFeaturesConfig

Attributes
class stoat.InstanceFeaturesConfig(*, captcha, email_verification, invite_only, autumn, january, voice)[source]

Represents how features are configured on this Stoat instance.

captcha

The CAPTCHA configuration.

Type:

InstanceCaptchaFeature

email_verification

Whether is E-Mail verification required.

Type:

bool

invite_only

Whether this server is invite only.

Type:

bool

autumn

The configuration for Autumn (file server service).

Type:

InstanceGenericFeature

january

The configuration for January (embed server service).

Type:

InstanceGenericFeature

voice

The configuration for Vortex or Livekit (voice server service).

Type:

InstanceVoiceFeature

InstanceBuild

Attributes
class stoat.InstanceBuild(*, commit_as_sha, committed_at, semver, origin_url, built_at)[source]

Represents information about instance build.

Warning

Some fields might be None, empty string or have '<failed to generate>' value if they are unavailable. Never assume that they will be available.

commit_as_sha

'a52d610e6c152e7acc23cd017a7c67af46eace4c'.

Type:

str

Type:

The commit hash. For example

committed_at

When last commit was at.

Type:

Optional[datetime]

semver

'20240710-1-157-ga52d610'.

Type:

str

Type:

The build tag. Example

origin_url

'https://github.com/revoltchat/backend'.

Type:

str

Type:

The origin URL. Example

built_at

When the instance executables were built at. This is different from committed_at.

Type:

Optional[datetime]

Instance

Attributes
class stoat.Instance(*, version, features, websocket_url, app_url, vapid_public_key, build)[source]

Represents a Stoat instance.

version

The API version.

Type:

str

features

The configuration of features enabled on this Stoat node.

Type:

InstanceFeaturesConfig

websocket_url

The WebSocket URL.

Type:

str

app_url

The web application URL.

Type:

str

vapid_public_key

The VAPID public key, used for WebPush.

Type:

str

build

The information of build of this instance.

Type:

InstanceBuild

PolicyChange

Attributes
class stoat.PolicyChange(*, created_at, effective_at, description, url)[source]

Represents a platform policy change.

To acknowledge the policy changes, call HTTPClient.acknowledge_policy_changes().

Added in version 1.2.

created_at

When the policy change was created.

Type:

datetime

effective_at

When the policy change will take effect.

Type:

datetime

description

The message shown to users.

Type:

str

url

The URL with details about policy changes.

Type:

str

Exceptions

The following exceptions are thrown by the library.

exception stoat.StoatException[source]

Bases: Exception

Base exception class for stoat.py

Ideally speaking, this could be caught to handle any exceptions raised from this library.

Changed in version 1.2: Renamed from PyvoltException to StoatException.

Deprecated since version 1.2: The PyvoltException alias is a deprecated alias.

exception stoat.WebSocketConnectionFailure(*, status)[source]

Bases: Exception

Signal that WebSocket endpoint did not return “101 Switching Protocols” status code.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.HTTPException(response, data, /)[source]

Bases: StoatException

Exception that’s raised when a HTTP request operation fails.

This inherits from StoatException.

response

The response of the failed HTTP request.

Type:

HTTPResponse

data

The data of the error. Could be an empty string.

Type:

Union[Dict[str, Any], Any]

status

The status code of the HTTP request.

Type:

int

type

The Stoat specific error type for the failure.

Type:

str

retry_after

The duration in seconds to wait until ratelimit expires.

Type:

Optional[float]

error

The validation error details. Only applicable when type is 'FailedValidation'.

Type:

Optional[str]

max

The maximum count of entities. Only applicable when type one of following values:

  • 'FileTooLarge'

  • 'GroupTooLarge'

  • 'TooManyAttachments'

  • 'TooManyChannels'

  • 'TooManyEmbeds'

  • 'TooManyEmoji'

  • 'TooManyPendingFriendRequests'

  • 'TooManyReplies'

  • 'TooManyRoles'

  • 'TooManyServers'

Type:

Optional[int]

permission

The permission required to perform request. Only applicable when type one of following values:

  • 'MissingPermission'

  • 'MissingUserPermission'

Type:

Optional[str]

operation

The database operation that failed. Only applicable when type is 'DatabaseError'.

Type:

Optional[str]

collection

The collection’s name the operation was on. Not always available when type is 'DatabaseError'.

Type:

Optional[str]

location

The path to Rust location where error occured.

Type:

Optional[str]

with_

The collection’s name the operation was on. Only applicable when type one of following values: - 'IncorrectData'

Not always available when type is 'DatabaseError'.

Type:

Optional[str]

feature

The feature that was disabled. Only applicable when type is 'FeatureDisabled'.

Possible values:

  • 'features.mass_mentions_enabled'

Type:

Optional[str]

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.NoEffect(data, /)[source]

Bases: StoatException

HTTP exception that corresponds to HTTP 200 status code.

This exists because Stoat API returns 200 with error body for some reason.

This inherits from StoatException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.Unauthorized(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 401 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.Forbidden(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 403 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.NotFound(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 404 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.Conflict(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 409 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.Ratelimited(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 429 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.InternalServerError(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 5xx status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.BadGateway(response, data, /)[source]

Bases: HTTPException

HTTP exception that corresponds to HTTP 502 status code.

This inherits from HTTPException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.ShardError[source]

Bases: StoatException

Exception that’s raised when any shard-related error happens.

This inherits from StoatException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.ShardClosedError[source]

Bases: ShardError

Exception that’s raised when shard was already closed.

This inherits from ShardError.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.AuthenticationError(payload, /)[source]

Bases: ShardError

Exception that’s raised when WebSocket authentication fails.

This inherits from ShardError.

payload

The WebSocket payload.

Type:

Optional[Dict[str, Any]]

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.ConnectError(tries, errors, /)[source]

Bases: ShardError

Exception that’s raised when the library fails to connect to Stoat WebSocket.

This inherits from ShardError.

errors

The errors.

Type:

List[Exception]

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.DiscoverError(response, status, data, /)[source]

Bases: StoatException

Exception that’s raised when a HTTP request operation fails.

This inherits from StoatException.

response

The response of the failed HTTP request.

Type:

HTTPResponse

data

The data of the error. Could be an empty string.

Type:

Union[Dict[str, Any], Any]

status

The status code of the HTTP request.

Type:

int

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.InvalidData(reason, /)[source]

Bases: StoatException

Exception that’s raised when the library encounters unknown or invalid data from Stoat.

This inherits from StoatException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception stoat.NoData(what, type)[source]

Bases: StoatException

Exception that’s raised when the library did not found data requested from cache.

This is different from NotFound, and inherits from StoatException.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.