Skip to content

Function Definitions

Jump to bottom
mattventura edited this page Jun 19, 2014 · 3 revisions

Data, Communication, Logging

logdata

Logdata checks if logging is enabled, and if so, writes the specified data to the logfile.

logdata(data)

  • data (string): The data to be logged.

senddata

senddata sends data to the server, as well as outputting it to the console and the log.

senddata(data, alt = False)

  • data (string): The data to be sent. If the data is multiple lines, they will be sent one at a time. Note that if you send multiple lines, you cannot use the alt argument.
  • alt (string or False): Alternate data to display on console/log (useful for censoring passwords and such)

First, if there are multiple lines, this function splits up the lines and calls itself once for each line. Then, it checks to make sure it doesn't need to wait due to throttling configured in the connection options. Then, it uses sendall() on the socket to send the data. Lastly, it prepends (servername)< to the string, outputs it to the console, and sends it to logdata().

dispdata

dispdata is used to display lines received from the server.

dispdata(data)

  • data (string): The data to show.

First, it splits the data into individual lines. Then, for each line, it prepends (servername)> . Then, it outputs each line to stdout. If it runs into encoding issues, it will replace unicode characters with ?. Finally, it sends the data to logdata().

showdbg

showdbg is used to print debugging info to the console.

showdbg(data)

  • data (string): The data to show

First, it splits it into individual lines. Then, it prepends (servername)* . Then, it prints each line, and sends it to logdata().

showErr

Exactly the same as showdbg, but prepends ! instead of *.

It is not recommended to use this directly. You should use reportErr.

reportErr

Logs an error, shows it with showErr, and stores it for later use.

reportErr(exception)

exception: Generally you will want to just use sys.exc_info() as this argument.

syscmd

Runs an external command.

bytes syscmd(command)

  • command (list of strings): The command and its arguments. One argument per list entry.

Returns a byte sequence representing the output of the command. Chances are, you'll want to decode() this.

User management

getlevel

Get the numerical level of a nick.

int getlevel(name)

  • name (string): The nick to check.

Returns the numerical level as int. Returns 0 if they're unregistered/not found.

getLevelStr

As above, but converts it to a friendly name.

string getlevel(name)

  • name (string): The nick to check

Returns the name of their privilege level, as a string.

levelToStr

Converts an arbitrary level to a string.

`string levelToStr(level)

  • level (int): The level to convert

Returns the name of the level, as a string.

hasPriv

Checks if a nickname has a certain privilege

bool hasPriv(nick, priv, default = 0)

  • nick (string): The nickname to check
  • priv (string): The privilege to check for
  • default (int): The default required level to check against in case this privilege is not defined in config.py, and the user has not been specifically granted or denied this privilege.

Checks if nick has privilege priv. Currently, this just means "is the user's level greater than config.reqprivlevels[priv] (assuming the value of default if this does not exist)". However, the ability to grant or deny specific privileges to individual users will likely be added soon.

userLookup

Looks up a user in the users file.

uEntry userLookup(authName)

  • authName (string): The name to look up

Tries to find the user authName in the users file (either users or ausers depending on what type of authentication mechanism has been selected. Returns False if that user cannot be found, otherwise returns a uEntry object which works like the other user objects, but without a nickname.

formatPerms

Formats some privileges into a more readable format.

string formatPerms(grant, deny, spacer = ' ')

  • grant (set of strings): The granted permissions.
  • deny (set of strings): The denied permissions.
  • spacer (string): What to put between each item

Returns each granted permission, prefixed with a plus, followed by each denied permission, prefixed with a minus. Separates each entry with spacer. For example, to get a comma-separated list of permissions that the nickname 'bob' has, you could do:

user = getAuth('bob')
result = formatPerms(user.grant, user.deny, ', ')

chgUserPass

chgUserPass(user, newPass)

  • user (string): Username
  • newPass (string): Password to change to

Attempts to find the user in the users file. If it finds them, changes their password to newPass. Raises a UserNotFound exception if it can't.

chgUserLevel

chgUserLevel(user, level)

Like chgUserPass, but takes level as an integer, and attempts to change their level.

chgUserPrivs

chgUserPrivs(user, grant, deny)

As above, but takes grant and deny as sets of strings. This replaces current grants/denies, so if you don't want to start fresh you'll need to read the existing grants/denies and add/remove from them.

Module registry

registerfunction

Registers a standard command in a module, which will be called when a user invokes that command.

registerfunction(name, function)

  • name (string): The command that the user should run to invoke the function
  • function (function): The function within your module that should be run when the user types the name of the command.

The function will be added to funcregistry, which is a dictionary with the function name as the key and the function as the value.

addhelp

Registers a help function into the help system.

addhelp(name, function)

  • name (string): The command that the user should run to invoke the function
  • function (function): The function within your module that should be run when the user runs help <command>.

The function will be added to helpregistry, which is a dictionary with the function name as the key and the function as the value. Note that you can specify sub-commands (i.e. the user could run help command arg), and the help function can catch these since it is passed cmd in its helpCmd object. Note that the cmd passed in does not include help itself.

addlistener

Registers a function to listen for a particular type of event.

addlistener(event, function)

  • event (string): The type of event that should be listened for. See below for notes.
  • function (function): The function within the module to call.

Types of events

These types of events are defined in the bot, and work exactly as you would expect.

  • nick
  • quit
  • part
  • join
  • privmsg
  • ping
  • error

You can still listen for other events. Just use the name of the event exactly as it would be received for the server (e.g. PONG or 352).

There are two special events:

  • any: Listens for any event
  • periodic: Runs if the bot has not received data from the server in a few seconds.

Module Mangament

reloadByName

Attempts to reload a module.

bool reloadByName(modName)

  • modName (string): The name of the module to attempt to reload. This is the filename sans extension.

Returns True if the module was reloaded successfully, False otherwise. The reason this function is important is because it also flushes references to outdated versions of functions out of the registry lists. Simply doing a reload() on a module is not sufficient if you want changes to a module to be reflected.

Clone this wiki locally