Futurism › object › dAmn
From Botdom Documentation
The dAmn object handles Futurism's connection to dAmn and has all methods that interact with dAmn according to the protocol standard. Around half of these methods are internal protocol methods that should not be called from outside elements such as modules.
Properties
- str dAmn._buffer — Variable holding any temporarily incomplete packets from dAmn until the other half is recieved.
- dict dAmn.chats — A dictionary of each joined ns and their dAmnNs-inherited objects with ns information.
- dict dAmn.clientargs — A dictionary of arguments being sent from the client on handshake. Default includes only the required agent argument, with bot version info.
- str dAmn.clientver — The current version of the dAmn protocol that this client supports. Default: 0.3
- int dAmn.connecttime — The unix timestamp we got connected to dAmn. Is None before connection is established.
- dict dAmn.deferreds — A dictionary of each uncallbacked deferred and their defer.Deferred object.
- tuple dAmn.officials — A tuple of official dAmn chatrooms which cannot be joined.
- list dAmn.server — A list with two items: the dAmn server address and the dAmn server port. Default: chat.deviantart.com and 3900.
- str dAmn.serverver — The current version of the dAmn protocol that this server runs. Is None before connection is established.
- dict dAmn.userinfo — A dictionary of user information about the deviant we're logged in as. Recieved on login; is None before successful login.
Methods
pkt_ methods
Handling of incoming dAmn packets in Futurism are splitted up in a method in the dAmn object for each incoming packet cmd, all prefixed with pkt_, e.g. pkt_join for an incoming join packet. As such, there is such a method for each type of incoming dAmn packet. They will not be listed here, because they all more or less do the same. They parse the packets and print and log them as needed. They take care of the bot's standard parsing and also hooks events for modules.
These are executed when we have received a reaction from the dAmnServer to a command we sent them. And, theoretically, that doesn't happen instantly after the command is sent, so methods that execute commands (such as dAmn.join) don't return a result when executed, but it returns what is called a Deferred and is a term that comes from the Twisted framework. In short, a Deferred is an object that represents data that isn't available yet, and you can assign callbacks to it, which are called when the data is available, and that way you can execute code when the data is available.
instance dAmn.action(str msg, str ns)
Sends the message found in msg to the ns found in ns as an action (/me). Returns a Deferred to which callbacks can be added.
instance dAmn.admin(str cmd, str ns)
Attempts to execute the admin command (like update privclass Members +icons) found in cmd, in the ns found in ns. Returns a Deferred to which callbacks can be added.
instance dAmn.ban(str user, str ns)
Attempts to ban (demote to a privclass with -join) the user specified in user in the ns found in ns. Returns a Deferred to which callbacks can be added.
instance dAmn.connectionMade()
This method is called by Twisted when we've successfully established a connection. Sends the handshake packet and returns a new Deferred instance for the server's reply to the handshake packet. Should not be called from a module.
void dAmn.dataReceived(str data)
This method is called by Twisted when we receive data. Calls the appropiate pkt_ method to handle the packet. Should not be called from a module.
bool dAmn.deferredCallback(str name, instance pkt)
This method attempts to callback the deferred given by name, e.g. found in dAmn.deferreds with a key equal to the text in name. Should not be called manually from a module.
str dAmn.deferredName(instance pkt)
This method guesses the name of the given pkt's deferred object in dAmn.deferreds (also known as the defername). Returns in the format cmd:param except for packets with special rules.
instance dAmn.demote(str user, str ns[, str newpc])
Attempts to demote the user found in the user argument in the ns found in the ns argument. If newpc is a privclass name, it will attempt to demote to this privclass. Returns a Deferred to which callbacks can be added.
str dAmn.formatns(str ns)
Takes a raw ns string (e.g. chat:Botdom) and returns a formatted version (e.g. #Botdom).
fns = dAmn.formatns("chat:killerrabbit") # fns is: #killerrabbit fns = dAmn.formatns("pchat:botname:username") # fns is: @username fns = dAmn.formatns("pchat:someone:someoneelse") # fns is: @someone:someoneelse fns = dAmn.formatns("#Botdom") # fns is: #Botdom
instance dAmn.get(str property, str ns)
Attempts to get the property type found in property in the ns found in ns. Returns a Deferred to which callbacks can be added.
instance dAmn.kick(str user, str ns[, str reason])
Attempts to kick the user found in the user argument from the ns found in the ns argument. If reason is not empty, it will give this as a reason for the kick. Returns a Deferred to which callbacks can be added.
instance dAmn.join(str ns)
Attempts to join the ns found in the ns argument. Returns a Deferred to which callbacks can be added. If the ns is an official room (found in dAmn.officials), the method does not return a Deferred but instead returns False and does not send anything.
void dAmn.login()
Attempts to log in to dAmn with the credentials found in the configuration. It needs username and either password or authtoken to work. If an authtoken is not present in the configuration and a password is, the authtoken is resolved from the password. If there is no bot username or bot owner found in the configuration, it returns False, stops the reactor and quits. If there is no means of authentication, it also stops the reactor and quits.
instance dAmn.me(str msg, str ns)
Alias of dAmn.action.
instance dAmn.msg(str msg, str ns[, str mode])
Alias of dAmn.say.
instance dAmn.newDeferred(str cmd, str param)
Creates a new Deferred object from the inputted packet cmd and param, stores it in the dAmn.deferreds dict and returns it for adding callbacks and errbacks. Should not be called from a module directly.
instance dAmn.npmsg(str msg, str ns)
Sends the message found in msg to the ns found in ns as an npmsg (un-parsed, like holding shift on dAmn). Returns a Deferred to which callbacks can be added.
void dAmn.pong()
Sends a pong packet to the server to verify the connection. Is sent every time the server sends a ping packet.
str dAmn.parsetablumps(str msg[, str mode])
Parses tablumps from inputted str msg, to original HTML code (which is suitable for displaying in a Terminal). The mode argument is thought as one that alters how tablumps are parsed, for other medias, but is not functional yet, and as such, changing this makes no difference. Default is "log".
s = dAmn.parsetablumps("yes &b and&/b no") #s is: yes <b>and</b> no
instance dAmn.part(str ns)
Attempts to part the ns found in the ns argument. Returns a Deferred to which callbacks can be added.
instance dAmn.promote(str user, str ns[, str newpc])
Attempts to promote the user found in the user argument in the ns found in the ns argument. If newpc is a privclass name, it will attempt to promote to this privclass. Returns a Deferred to which callbacks can be added.
instance dAmn.say(str msg, str ns[, str mode])
Sends the message found in msg to the ns found in ns. The mode argument changes the mode with which the message is sent. The default is msg main, and other methods like dAmn.action and dAmn.npmsg utilizes different modes. Returns a Deferred to which callbacks can be added.
void dAmn.sendPacket(str data)
Appends a null character at the end of the raw packet string, data, and writes it to the transport (sends it off to dAmn). For sending raw packets, this method is best used in conjunction with the dAmn outgoing packet class, dAmnPacketO:
dAmn.sendPacket(dAmnPacketO("kick", ns, {"u": user}, reason)) # The dAmnPacketO instance is seen as a str by the sendPacket method and is thus read and sent as one # Refer to dAmnPacketO documentation on how that is built up
However, it is recommended that you use one of the other available methods to send your outgoing packets, instead of turning to the raw sendPacket, as sendPacket itself does not return a Deferred and thus, you will not be alerted when your packet is responded.
instance dAmn.set(str property, str value, str ns)
Attempts to set the property type found in property in the ns found in ns to the value found in value. Returns a Deferred to which callbacks can be added.
instance dAmn.unban(str user, str ns)
Attempts to unban (promote to Guests privclass) the user specified in user in the ns found in ns. Returns a Deferred to which callbacks can be added.
str dAmn.unformatns(str ns)
Takes a formatted ns string (e.g. #Botdom) and returns a raw, unformatted version (e.g. chat:Botdom).
ns = dAmn.unformatns("#killerrabbit") # ns is: chat:killerrabbit ns = dAmn.unformatns("@username") # ns is: pchat:botdom:username ns = dAmn.unformatns("@someone:someoneelse") # ns is: pchat:someone:someoneelse ns = dAmn.unformatns("chat:Botdom") # ns is: chat:Botdom
