API Reference¶

Core Modules¶

Client¶

class pyshowdown.client.Client(username, password, url, login_type='password', ssl_context=None)¶

Bases: object

__init__(username, password, url, login_type='password', ssl_context=None)¶

Client class constructor.

Parameters:

username (str) – The username to use.
password (str) – The password to use.
url (str) – The url to connect to.
login_type (str) – The type of login to use. Either “password” or “oauth”.
ssl_context (ssl.SSLContext, optional) – The SSL context. Defaults to None.

__repr__()¶

Returns a representation of the client.

Returns:: The representation of the client.
Return type:: str

__str__()¶

Returns a string representation of the client.

Returns:: The string representation of the client.
Return type:: str

async close()¶

Close the connection.

Return type:: None

async connect()¶

Connect to the server.

Return type:: None

async handle_message(room, msg_str)¶

Handles a message from the server.

Iterates through all the loaded plugins, determines whether any of them can handle the message, and if so, calls the response method of the plugin.

Parameters:

room (str) – The room the message was sent from.
msg_str (str) – The message received.

Return type:

None

async join(room)¶

Joins the given room.

Parameters:: room (str) – The room to join.
Return type:: None

async keep_connected()¶

Keeps the client connected to the server.

Return type:: None

async leave(room)¶

Leaves the given room.

Parameters:: room (str) – The room to leave.
Return type:: None

load_plugin(plugin_name)¶

Load a single plugin by name.

The plugin module must export a setup(client) function that returns a list of BasePlugin instances.

Parameters:: plugin_name (str) – The name of the plugin module to load.
Returns:: True if plugin loaded successfully, False otherwise.
Return type:: bool

static print(msg)¶

Prints a message. Intended to be possible to be overridden.

Parameters:: msg (str) – The message to be printed.
Return type:: None

async receive()¶

Receives data from the server.

Returns:: The data received.
Return type:: aiohttp.WSMessage

async receive_forever()¶

Receives data from the server forever.

Raises:: ConnectionError – If no connection is established.
Return type:: None

async send(room, message)¶

Sends message to the server.

Parameters:: message (str) – The message to send.
Return type:: None

async send_pm(user, message)¶

Sends a private message to the user.

Parameters:

user (str) – The user to send the message to.
message (str) – The message to send.

Return type:

None

async start_message_queue()¶

Starts the message queue.

Return type:: None

Connection¶

class pyshowdown.connection.Connection(url, ssl_context=None)¶

Bases: object

__init__(url, ssl_context=None)¶

Create a connection to the server.

Parameters:

url (str) – The url to connect to.
ssl_context (ssl.SSLContext, optional) – The SSL context. Defaults to None.

__repr__()¶

Return a representation of the connection.

Returns:: The representation of the connection.
Return type:: str

__str__()¶

Return a string representation of the connection.

Returns:: The string representation of the connection.
Return type:: str

async close()¶

Close the connection to the server.

Raises:: ConnectionError – If no connection is established.
Return type:: None

async connect()¶

Connect to the server.

Return type:: None

async receive()¶

Receive a message from the server.

Returns:: The message received.
Return type:: aiohttp.WSMessage
Raises:: ConnectionError – If no connection is established.

async send(message)¶

Send a message to the server.

Parameters:: message (str) – The message to send.
Raises:: ConnectionError – If no connection is established.
Return type:: None

Message¶

class pyshowdown.message.BattleMessage(room, message_str, roomid, user1, user2)¶: Bases: Message

class pyshowdown.message.ChallstrMessage(room, message_str, challstr)¶: Bases: Message

class pyshowdown.message.ChatMessage(room, message_str, user, message, timestamp=None)¶: Bases: Message

class pyshowdown.message.DeinitMessage(room, message_str)¶: Bases: Message

class pyshowdown.message.ErrorMessage(room, message_str, error)¶: Bases: Message

class pyshowdown.message.FormatsMessage(room, message_str, formats)¶: Bases: Message

class pyshowdown.message.HTMLMessage(room, message_str, html)¶: Bases: Message

class pyshowdown.message.InitMessage(room, message_str, roomtype)¶: Bases: Message

class pyshowdown.message.JoinMessage(room, message_str, user)¶: Bases: Message

class pyshowdown.message.LeaveMessage(room, message_str, user)¶: Bases: Message

class pyshowdown.message.Message(room, message_str)¶

Bases: object

__init__(room, message_str)¶

Initialize a Message object.

Parameters:

room (str) – The room the message was sent to.
message_str (str) – The raw message.

__repr__()¶

Return a representation of the message.

Returns:: A representation of the message.
Return type:: str

__str__()¶

Return a string representation of the message.

Returns:: A string representation of the message.
Return type:: str

class pyshowdown.message.NameTakenMessage(room, message_str, user, message)¶: Bases: Message

class pyshowdown.message.PMMessage(room, message_str, user, receiver, message)¶: Bases: Message

class pyshowdown.message.PageHTMLMessage(room, message_str, html)¶: Bases: Message

class pyshowdown.message.PlayerMessage(room, message_str, player, name, avatar, rating)¶: Bases: Message

class pyshowdown.message.PopupMessage(room, message_str, message)¶: Bases: Message

class pyshowdown.message.QueryResponseMessage(room, message_str, query_type, json_data)¶

Bases: Message

handle()¶

class pyshowdown.message.RawMessage(room, message_str, data)¶: Bases: Message

class pyshowdown.message.RenameMessage(room, message_str, user, oldid, status_str)¶: Bases: Message

class pyshowdown.message.TimestampMessage(room, message_str, timestamp)¶: Bases: Message

class pyshowdown.message.TitleMessage(room, message_str, title)¶: Bases: Message

class pyshowdown.message.UHTMLChangeMessage(room, message_str, name, html)¶: Bases: Message

class pyshowdown.message.UHTMLMessage(room, message_str, name, html)¶: Bases: Message

class pyshowdown.message.UpdateChallengesMessage(room, message_str, json)¶: Bases: Message

class pyshowdown.message.UpdateSearchMessage(room, message_str, json)¶: Bases: Message

class pyshowdown.message.UpdateUserMessage(room, message_str, user, named, avatar, settings)¶: Bases: Message

class pyshowdown.message.UserCountMessage(room, message_str, usercount)¶: Bases: Message

class pyshowdown.message.UsersMessage(room, message_str, usercount, users)¶: Bases: Message

class pyshowdown.message.WinMessage(room, message_str, winner)¶: Bases: Message

pyshowdown.message.parse_formats(format_str)¶

Parse a format message and return a list of formats.

Parameters:

format_str (str) – The format message.

Returns:

A dictionary of sections, formats, and some additional: info about the formats.

Return type:

formats

pyshowdown.message.parse_message(room, message_str)¶

Return type:: Message

Room¶

class pyshowdown.room.Room(id)¶

Bases: object

__init__(id)¶

Represents a PS room.

Parameters:: id (str) – The room ID.

User¶

class pyshowdown.user.User(name, rank, status, away)¶

Bases: object

__init__(name, rank, status, away)¶

Represents a user.

Parameters:

name (str) – The user’s name, without rank.
rank (str) – The user’s rank.
status (str) – The user’s status.
away (bool) – Whether the user is away.

property fullname: str¶: Return the user’s name with rank.

to_string()¶

Return the user’s name with rank and status.

Return type:: str

Utils¶

pyshowdown.utils.HSLToRGB(H, S, L)¶

Convert HSL to RGB.

Return type:: tuple

pyshowdown.utils.to_id(string)¶

Convert a string to an ID.

Return type:: str

pyshowdown.utils.username_color(name)¶

Get the color of a username.

Return type:: tuple

Plugins¶

Plugin Base¶

class pyshowdown.plugins.plugin.BasePlugin(client)¶

Bases: Generic[MessageType]

__init__(client)¶

Initializes the plugin.

Parameters:: client (Client) – A reference to the client.

async match(message)¶

Returns True if the message is a match for the plugin.

Parameters:: message (Message) – The message to check.
Raises:: NotImplementedError – Always, since this is a base class.
Returns:: True if the message is a match, False otherwise.
Return type:: bool

async response(message)¶

Returns the response for the message.

Parameters:: message (MessageType) – The message to respond to.
Raises:: NotImplementedError – Always, since this is a base class.
Returns:: The response for the message.
Return type:: Optional[str]

scrollback_access: bool = False¶

Challstr¶

class pyshowdown.plugins.challstr.ChallstrHandler(client)¶

Bases: BasePlugin[ChallstrMessage]

async match(message)¶

Returns true if the message is a challstr.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a challstr, False otherwise.
Return type:: bool

async response(message)¶

Responds to a challstr message and logs in.

Parameters:: message (ChallstrMessage) – The message to respond to.
Return type:: None

async pyshowdown.plugins.challstr.load_cookies(filename='cookies.json')¶

Load cookies from a JSON file into a new CookieJar.

Parameters:: filename (str) – The name of the file to load cookies from.
Return type:: Optional[CookieJar]

async pyshowdown.plugins.challstr.password_login(client, challstr)¶

Tries to log in using a password.

Parameters:

client (Client) – The client to log in.
challstr (str) – The challstr to use.

Return type:

None

async pyshowdown.plugins.challstr.save_cookies(cookie_jar, filename='cookies.json')¶

Save cookies from an aiohttp CookieJar to a JSON file.

Parameters:

cookie_jar (AbstractCookieJar) – The cookie jar to save.
filename (str) – The name of the file to save cookies to.

Return type:

None

pyshowdown.plugins.challstr.setup(client)¶

Creates an instance of the ChallstrHandler plugin and returns it.

Parameters:: client (Client) – A reference to the client.
Returns:: A list containing the ChallstrHandler plugin.
Return type:: List[BasePlugin]

Deinit¶

class pyshowdown.plugins.deinit.DeinitHandler(client)¶

Bases: BasePlugin[DeinitMessage]

async match(message)¶

Returns true if the message is a deinit message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a deinit message, False otherwise.
Return type:: bool

async response(message)¶

Removes the room from the Client’s room dict.

PS also sends a deinit message if you join a room using a room alias (appearing as if from the alias room), so we should check if we have it first.

Parameters:: message (DeinitMessage) – The deinit message.
Return type:: None

pyshowdown.plugins.deinit.setup(client)¶

Return a list of plugins to load.

Parameters:: client (Client) – The client to use.
Returns:: A list of plugins to load.
Return type:: List[BasePlugin]

Init¶

class pyshowdown.plugins.init.InitHandler(client)¶

Bases: BasePlugin[InitMessage]

async match(message)¶

Returns true if the message is an init message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is an init message, False otherwise.
Return type:: bool

async response(message)¶

Creates the room in the Client’s room dict.

Parameters:: message (InitMessage) – The init message.
Return type:: None

class pyshowdown.plugins.init.TimestampHandler(client)¶

Bases: BasePlugin[TimestampMessage]

async match(message)¶

Returns true if the message is a timestamp message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a timestamp message, False otherwise.
Return type:: bool

async response(message)¶

Sets the room timestamp in the Client’s room dict.

Parameters:: message (TimestampMessage) – The timestamp message.
Return type:: None

pyshowdown.plugins.init.setup(client)¶

Return a list of plugins to load.

Parameters:: client (Client) – The client to use.
Returns:: A list of plugins to load.
Return type:: List[BasePlugin]

Title¶

class pyshowdown.plugins.title.TitleHandler(client)¶

Bases: BasePlugin[TitleMessage]

async match(message)¶

Returns true if the message is a title message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a title message, False otherwise.
Return type:: bool

async response(message)¶

Sets the room title in the Client’s room dict.

Parameters:: message (TitleMessage) – The title message.
Return type:: None

pyshowdown.plugins.title.setup(client)¶

Return a list of plugins to load.

Parameters:: client (Client) – The client to use.
Returns:: A list of plugins to load.
Return type:: List[BasePlugin]

Users¶

class pyshowdown.plugins.users.JoinHandler(client)¶

Bases: BasePlugin[JoinMessage]

async match(message)¶

Returns true if the message is a join message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a join message, False otherwise.
Return type:: bool

async response(message)¶

Adds the user to the room’s users.

Parameters:: message (JoinMessage) – The join message.
Return type:: None

class pyshowdown.plugins.users.LeaveHandler(client)¶

Bases: BasePlugin[LeaveMessage]

async match(message)¶

Returns true if the message is a leave message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a leave message, False otherwise.
Return type:: bool

async response(message)¶

Removes the user from the room’s users.

Parameters:: message (LeaveMessage) – The leave message.
Return type:: None

class pyshowdown.plugins.users.RenameHandler(client)¶

Bases: BasePlugin[RenameMessage]

async match(message)¶

Returns true if the message is a rename message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a rename message, False otherwise.
Return type:: bool

async response(message)¶

Renames the user in the room’s users.

Parameters:: message (RenameMessage) – The rename message.
Return type:: None

class pyshowdown.plugins.users.UsersHandler(client)¶

Bases: BasePlugin[UsersMessage]

async match(message)¶

Returns true if the message is a users message.

Parameters:: message (Message) – The message to check.
Returns:: True if the message is a users message, False otherwise.
Return type:: bool

async response(message)¶

Sets the room users in the Client’s room dict.

Parameters:: message (UsersMessage) – The users message.
Return type:: None

pyshowdown.plugins.users.setup(client)¶

Return a list of plugins to load.

Parameters:: client (Client) – The client to use.
Returns:: A list of plugins to load.
Return type:: List[BasePlugin]

API Reference¶

Core Modules¶

Client¶

Connection¶

Message¶

Room¶

User¶

Utils¶

Plugins¶

Plugin Base¶

Challstr¶

Deinit¶

Init¶

Title¶

Users¶

pyshowdown

Navigation

Related Topics