API Reference

This is a list of every function decent.py provides, along with all the information you’ll need to use them.

Server

class Server(url, username, password)

A connection to a Decent server.

Parameters:
  • url (str) – The URL of the Decent server
  • username (str) – The username of the user being logged in
  • password (str) – The password of the user being logged in
Variables:
  • channels (list[Channel]) – A list of all channels in the server
  • emotes (list[Emote]) – A list of all emotes in the server
  • pretty_url (str) – The URL without a protocol or trailing slash
  • session_id (str) – The ID of the current session
  • url (str) – The URL of the Decent server
  • user (User) – The currently logged in user
  • users (list[User]) – A list of all users on the server
connect()

Connects to the Decent server, logs in with the given username and password, and opens a websocket connection.

Raises:DecentError – if the server is invalid or if there is an error logging in
create_channel(name)

Creates a new channel in the server.

Parameters:name (str) – The name of the channel
Returns:the newly created Channel object
get_channel(cid)

Gets a channel from a channel ID.

Parameters:cid (str) – The channel ID
Returns:a Channel object with the given ID
get_message(mid)

Gets a message from a message ID.

Parameters:mid (str) – The message ID
Returns:a Message object with the given ID
get_user(uid)

Gets a user from a user ID.

Parameters:uid (str) – The user ID
Returns:a User object with the given ID
mainloop()

Receives websocket data from the server and does stuff with it. Call this method regularly (usually in a while loop) and it will call your event functions decorated with Server.event(), respond to ping events, and update the class when new channels or users are created.

Raises:DecentError – if the Server object has not been properly initialized (via Server.connect()) before calling mainloop.
@event

Sets up the decorated function to be called by Server.mainloop().

Possible functions (must have one of these names):

  • on_message(message) - gets called whenever a new message is sent. message is a Message object.
  • on_edit(message) - gets called whenever a message is edited. message is a Message object.
  • on_channel_new(channel) - gets called whenever a new channel is created. channel is a Channel object.
  • on_channel_update(channel) - gets called whenever a channel is updated (renamed, marked as read, etc.) channel is a Channel object.
  • on_channel_delete(channel) - gets called whenever a channel is deleted. channel is a Channel object.
  • on_pin_add(message) - gets called whenever a message is pinned to a channel. message is a Message object.
  • on_pin_remove(mid) - gets called whenever a message is unpinned from a channel. mid is a string.
  • on_user_new(user) - gets called whenever a new user joins the server or is authorized (on a server that requires authorization). user is a User object.
  • on_user_gone(uid) - gets called whenever a user leaves the server or is deauthorized (on a server that requires authorization). uid is a string.
  • on_user_online(user) gets called whenever a user who was offline before becomes online. user is a User object.
  • on_user_offline(user) gets called whenever a user who was online before becomes offline. user is a User object.
  • on_user_update(user) - gets called whenever a user is updated. user is a User object.
  • on_user_mention(message) - gets called whenever a user is mentioned in a message. message is a Message object.
  • on_user_unmention(mid) - gets called whenever a message mentioning a user is edited or deleted to unmention the user. mid is a string.
  • on_emote_new(emote) - gets called whenever a new emote is created. emote is a Emote object.
  • on_emote_delete(shortcode) - gets called whenever an emote is deleted. shortcode is a string.

Channel

class Channel(server, cid, name[, unread_count])

A Decent channel. Belongs to a server, and messages can be sent and received in channels. You’ll rarely if ever use the constructor - Channel objects are normally initialized for you automatically.

Parameters:
  • server (Server) – The server that the channel belongs to
  • cid (str) – The channel ID
  • name (str) – The name of the channel
  • unread_count (str) – The number of unread messages in the channel
Variables:
  • cid (str) – The channel ID
  • name (str) – The name of the channel
  • unread_count (str) – The number of unread messages in the channel
pins

The pinned messages in the channel.

classmethod from_json(server, json)

Constructs a Channel object from a JSON object returned by a Decent server.

Parameters:
  • server (Server) – The server that the channel belongs to
  • json (dict) – The JSON object from the Decent server.
delete()

Deletes the channel.

latest_messages([before[, after[, limit]]])

Gets the latest messages in the channel. If before is specified, it will only return messages sent before the message ID specified in before, and if after is specified, it will only return messages sent after the message ID specified in after.

Parameters:
  • before (str) – A message ID - only return messages before this message
  • after (str) – A message ID - only return messages after this message
  • limit (int) – The maximum number of messages to fetch. Default is 50, must be 1 <= limit <= 50.
Returns:

a list of Message objects.
mark_read()

Marks the channel as read.

rename(new_name)

Renames the channel to new_name.

Parameters:new_name (str) – The new name of the channel.
send(text)

Sends a new message in the channel.

Parameters:text (str) – The text of the message to send.
Returns:the newly created Message object.
static by_id(server, cid)

Gets a channel by its ID in server server.

Parameters:
  • server (Server) – The server object to look in
  • cid (str) – The channel ID to search for

Message

class Message(server, mid, author, channel, text, date, edit_date, reactions, mentions)

A message sent in a Decent channel. Again, the constructor will rarely, if ever, be used.

Parameters:
  • server (Server) – The server that the message belongs to
  • mid (str) – The message ID
  • author (User) – The author of the message
  • channel (Channel) – The channel that the message was sent in
  • text (str) – The text of the message
  • date (datetime) – The date/time the message was sent
  • edit_date (datetime) – The date/time the message was edited
  • reactions (list[Emote]) – The reactions attached to the message
  • mentions (list[User]) – The users mentioned in the message
Variables:
  • server (Server) – The server that the message belongs to
  • mid (str) – The message ID
  • author (User) – The author of the message
  • channel (Channel) – The channel that the message was sent in
  • text (str) – The text of the message
  • date (datetime) – The date/time the message was sent
  • edit_date (datetime) – The date/time the message was edited
  • reactions (list[Emote]) – The reactions attached to the message
  • mentions (list[User]) – The users mentioned in the message
classmethod from_json(server, json)

Constructs a Message object from a JSON object returned by a Decent server.

Parameters:
  • server (Server) – The server that the message belongs to
  • json (dict) – The JSON object from the Decent server
edit(newtext)

Edits the message and replaces the text with newtext.

Parameters:newtext (str) – The new text of the message

User

class User(server, uid, username, perm_level, flair, online, avatar_url[, email[, authorized]])

A user on a Decent server. Again, the constructor is rarely, if ever, used.

Parameters:
  • server (Server) – The server that the user belongs to
  • uid (str) – The user’s ID
  • username (str) – The user’s username
  • perm_level (str) – The permission level ("admin" or "member")
  • flair (str) – The user’s flair
  • online (bool) – The online/offline status of the user
  • avatar_url (str) – The URL of the user’s avatar
  • email (str) – The user’s email
  • authorized (bool) – The user’s authorization status
Variables:
  • server (Server) – The server that the user belongs to
  • uid (str) – The user’s ID
  • username (str) – The user’s username
  • perm_level (str) – The permission level ("admin" or "member")
  • flair (str) – The user’s flair
  • online (bool) – The online/offline status of the user
  • avatar_url (str) – The URL of the user’s avatar
  • email (str) – The user’s email
  • authorized (bool) – The user’s authorization status
classmethod from_json(server, json)

Creates a User object from a JSON object returned by a Decent server.

Parameters:
  • server (Server) – The server that the user belongs to
  • json (dict) – The JSON object from the Decent server
authorize()

Authorizes the user.

deauthorize()

Deauthorizes the user.

static by_id(server, uid)

Returns a user from server server with ID uid.

Parameters:
  • server (Server) – The server to search in
  • uid (str) – The user ID to search for
Returns:

a User object
Raises:

DecentError – if a user with the given ID is not found in the server.

Emote

class Emote(server, shortcode, image_url)

An emote on a Decent server.

Parameters:
  • server (Server) – The server that the emote belongs to
  • shortcode (str) – The :shortcode: of the emote
  • image_url (str) – The URL of the emote’s image
Variables:
  • server (Server) – The server that the emote belongs to
  • shortcode (str) – The :shortcode: of the emote
  • image_url (str) – The URL of the emote’s image
classmethod from_json(server, json)

Creates an Emote object from a JSON object returned by a Decent server.

Parameters:
  • server (Server) – The server that the emote belongs to
  • json (dict) – The JSON object from the Decent server
static by_shortcode(server, shortcode)

Returns an emote from server server with shortcode shortcode.

Parameters:
  • server (Server) – The server to search in
  • shortcode (str) – The shortcode to search for
Returns:

a Emote object
Raises:

DecentError – if an emote with the given shortcode is not found in the server.