API Documentation#

Naming#

Generally, functions like get_xxxx use cached values and functions like fetch_xxxx block while waiting for a response from the server. Functions like list_xxxx generally return multiple items, usually but not always from cache.

Classes#

class asterpy.Client(username, password)#

Asterpy client that can be connected to multiple servers

Attributes

servers: list[Server]#

Methods

@event(self, fn)#
Register an event handler with the client. Used as a decorator. Possible event handlers are:

  • on_message: Called when any message is received in any channel. fn must take one argument of type Message

  • on_packet: Called when any packet of any kind is received. fn must take one argument of type dict

  • on_ready: Called when the client is finished initialising. fn must take no arguments.

__init__(username, password)#
Parameters:

  • username (str) – the default username to use for connecting to servers

  • password (str) – the default password to use for connecting to servers

add_server(ip, port, *, username=None, password=None, uuid=None, connect_mode=ConnectionMode.LOGIN)#

Add a server to the list of servers to connect to.

Parameters:

  • ip (str) – the IP to connect to.

  • port (int) – the port to connect to.

  • uuid (int) – User ID to log in with. Prefer specifying this over specifying the username, as the UUID will not change even if you change the username.

  • username (str) – The username to log in with. If neither uuid or username are specified, the username passed to the constructor will be used.

  • password (str) – The password to log in with. If no password is provided, the password passed to the constructor will be used.

  • login – Whether or not to log in to this server.

  • register – Whether or not to register an account with this server.

get_user(uuid)#

Get the User object corrosponding to the given UUID. Prefer using the Server.get_user() method if you already have the Server object.

Parameters:

uuid (int) – The UUID of the user.

Return type:

Optional[User]

Returns:

The User object, or None if the user doesn’t exist.

get_channel(uuid)#

Get the Channel object associated with the given ID. Prefer using the Server.get_channel() method if you already have the Server object.

Parameters:

uuid (int) – The ID of the channel.

Return type:

Optional[Channel]

Returns:

The channel, or None if it doesn’t exist

get_channel_by_name(name)#

Get the Channel object by referring to its name. Generally, prefer using the ID to reference channels rather than the name if possible. Prefer using the Server.get_channel_by_name() method if you already have the Server object.

Parameters:

name (str) – The name of the channel.

Return type:

Optional[Channel]

Returns:

The channel, or None if it doesn’t exist.

async connect(init_commands=None)#

Connect to all servers.

run(init_commands=None)#

Wrapper to call connect() synchronously.

class asterpy.Server(ip, port, *, username=None, password=None, uuid=None, connect_mode=ConnectionMode.LOGIN)#

Represents a client connection to one server

Attributes

channels: list[Channel] = []#
peers: dict[int, User] = {}#

Map from UUIDs to Users

name: str = ''#

Server name

icon: bytes = b''#

PNG-encoded server picture

self_uuid#

UUID of logged in account on this server

Methods

__init__(ip, port, *, username=None, password=None, uuid=None, connect_mode=ConnectionMode.LOGIN)#
async connect(init_commands=None)#

Connect to the server and listen for packets. This function blocks until Client.disconnect() is called.

Parameters:

init_commands (Optional[List[dict]]) – Optional list of packets to send to the server after connecting.

async disconnect()#

Disconnect from the server.

get_channel(uuid)#

Get the Channel object associated with the given ID.

Parameters:

uuid (int) – The ID of the channel.

Return type:

Optional[Channel]

Returns:

The Channel, or None if it doesn’t exist

get_channel_by_name(name)#

Get the Channel object by referring to its name. Generally, prefer using the ID to reference channels rather than the name if possible, as the name could change.

Parameters:

name (str) – The name of the channel.

Return type:

Optional[Channel]

Returns:

The channel, or None if it doesn’t exist.

get_user(uuid)#

Get the User object corrosponding to the given UUID.

Parameters:

uuid (int) – The UUID of the user.

Return type:

Optional[User]

Returns:

The User object, or None if the user doesn’t exist.

async fetch_user(uuid)#

Fetch a User fresh from the server. Send a new packet and get the result instead of using cached data. :type uuid: int :param uuid: The UUID of the user. :rtype: Optional[User] :returns: The User object, or None if the user doesn’t exist or another error occurred.

async fetch_emoji(uuid)#
Parameters:

uuid (int) – ID of the emoji to fetch.

Return type:

Emoji

async fetch_sync()#

Fetch the SyncData from the server.

Return type:

Optional[SyncData]

Returns:

The SyncData object, or None if the server has no sync data.

async list_emojis()#

Fetch a list of custom emojis from the server.

Return type:

List[Emoji]

async send(message)#

Send a packet to the server.

Parameters:

message (dict[any]) – The packet to send, as a dictionary.

async get_response(packet)#

Send a packet of data to the server and wait for a response. :type packet: dict :param packet: Data to be sent to the server as python dictionary, converted to JSON before sending. :rtype: dict :returns: The data from the server, decoded to a python dictionary.

class asterpy.ConnectionMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

How to authenticate with the aster server.

Attributes

LOGIN = 1#
REGISTER = 2#
NEITHER = 3#
class asterpy.Channel(client, name, uuid)#

Represents an aster channel.

Attributes

name#
uuid#

Methods

async send(message, reply_to=None)#

Send a text message to the channel.

Parameters:

  • message (str) – The text to be sent

  • reply_to (Optional[int]) – The UUID of the message to reply to, or None if not replying.

Returns:

The Message object that has been sent

async fetch_history(count=100, init_message=None)#

Fetch the last count messages from a given channel.

Parameters:

  • channel – The channel from which to fetch the messages.

  • count (int) – The number of messages to fetch. (defeault: 100)

  • init_message (Message) – Fetch count messages before this message. If init_message == None, then fetch the last count messages.

Return type:

list[Message]

Returns:

A list of messages.

class asterpy.User(uuid, username, pfp=None)#

Represents a user on the aster server

Attributes

uuid#
username#
pfp#

PNG-compressed image data

class asterpy.Message(content, user, channel, server, date, uuid, reply_uuid=None)#

Represents a message in a channel on the server

Attributes

content#
author#
channel#
date#

UNIX timestamp

reply_uuid#

UUID of the message this is replying to

async edit(new_content)#

Edit a message. The message must have been sent by the account attempting to edit it.

Parameters:

new_content (str) – The new body text of the message.

async delete()#

Delete this message. This message must be sent by the account that’s deleting it.

async reply(content)#

Reply to this message. Equivalent to sending a new message with the reply field set to this message’s UUID.

Returns:

The new Message object that was sent in reply.

class asterpy.Emoji(name, uuid, data)#

Represents a custom emoji

Attributes

data#

PNG-compressed image data as bytes.

name#
uuid#
class asterpy.SyncServer(ip, port, name, pfp, uuid)#

Represents a server entry in the SyncData.

Attributes

ip#
port#
pfp#

PNG-compressed image data

name#
uuid#

Methods

from_json()#

Create a SyncServer from an entry in the sync_get_servers packet.

Parameters:

value (dict) – The entry to deserialise.

Return type:

SyncServer

class asterpy.SyncData(uname, pfp, servers)#

Represents the data used to sync an aster account across multiple devices. This data can be stored on any aster server which the user designates their sync server. It contains information such as the current username, profile picture, and server list so they can be consistant across clients.

Attributes

uname#
pfp#
servers#

Methods

from_json(servers)#

Create a SyncData object from a sync_get packet and a sync_get_servers packet.

Parameters:

  • value (dict) – A dictionary containing sync data.

  • servers (dict) – A dictionary containing a list of sync server data.

Returns:

The SyncData object, or None if the packet’s status is 404 (no sync data on the server).

Return type:

Optional[SyncData]