Low-Level Modules

This is the general module API – the lower-level stuff, the stuff that UModule interfaces with.

Naming

Module filenames must be in the format of psm_yourmodulenamehere.py preferrably all lowercase.

Module classes must be in the format of PSModule_yourmodulenamehere, with both yourmodulenamehere’s being the same case.

For example, I may name my example module psm_example.py, with the class name PSModule_example.

Imports

All modules must import:

from psmodule import *

Class

All modules must extend PSModule

Class Variables

You should implement class variables:

  • VERSION = (number), up to you.

Additionally, the default __init__ sets several useful class variables for you to use in your module:

  • parent = object (received from __init__, your parent server
    object, e.g., TS6Protocol()).
  • config = object (received from __init__, the same
    configuration object used in the parent server object).
  • logchan = string (is set in __init__, channel from config
    where your bot users reside if you use one).
  • log = object (is set in __init__, file/stdout logger (usage:
    log.error(msg)|log.info(msg)…etc, see python logging lib for details).
  • dbp = object (is set in __init__, is the parent’s database
    pointer) – NB you should always make your own database if your module needs one.

Commands

There is only one sort of ‘command’ in the general module API. In UModule, these are called admin commands (acmds), and we will refer to them as such here.

acmd

Admin Commands are actual pypsd commands. To create an acmd_something.py library, simply add the functions you wish, and return the (function, usagestring) as a tuple from getCommands()

ACL flags, and Permissions

Each acmd has ‘ACL flags’ that you need to specify. This is essentially how the permissions in PyPsd currently work:

We can have 52 ACL flags, from a-z and A-Z.

When someone creates a module, they choose a character (a-zA-Z) that nobody else has picked yet, and that is essentially their module’s ‘access control’ mode character. For instance, for my new Twitter module, I might pick 'r'.

After you pick your character, make sure your commands have it in the ‘permission’ entry, as such:

def getCommands(self):
    return (
        ('disable', {
        'permission' : 'r',
        'callback' : self.cmd_disable,
        'usage' : '- Disable Twitter functionality'}),
    )

This means that users will need to have 'r' in their ACL flags list to run the twitter.disable acmd.

Examples of ACL flags lists:

  • IAmAGod: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
  • EverythingButShutdown: bcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
  • Power: efinopstuwxyzABCDEFGHIJKLMQRSTUVW
  • KindaOkay: ioqswyzCDEKQSTU
  • MidnightShiftGuy: ghvwDFRTVZ
  • TheTwitterGuy: r

It may also be useful to give different commands in the same module different flags. For instance, you may want to let someone restart your module, but not shut it down completely.

ACL flags list

Here’s a list of what different flags are used to control:

  • r: Core - Shutting down, and reloading PyPsd itself
  • m: Core – Module loading, unloading, and reloading
  • l: Core – Channel and user lookups
  • a: ACL – Removing and adding ACL flags from users
  • b: Bouncer – Blacklists based on CIDR blacklists
  • b: ProxyBridge – Scan users for proxies, and take action
  • d: Debugger – Debugging PyPsd, log searching and terminal commands
  • d: DNS Blacklist – Controlling a DNS blacklist
  • e: eRepublik – Online, global strategy game
  • e: e-Sim – Another online game, like eRepublik
  • e: Internets – Controls access to all of Interents’ admin commands
  • j: LimitServ – Controls number of users in channels?
  • j: Ninja – Keeps privmsgs from being posted heaps of times
  • j: Quotes – Keeping a local quote database
  • j: Trivia – Running trivia games
  • r: DynLogLevel – Changing PyPsd’s logging level
  • r: WALLOPS – Redirects WALLOPS to a channel
  • s: NetStats – Keeps network statistics
  • v: CTCP – CTCP info collecting and blacklisting
  • w: WikiMonitor – Monitors Wikis
  • x: Xray – Scans nicks, channel names, etc given provided regexes
  • A: AKILL – AKILLing users, removing AKILLs
  • B: ListBots – Lists important bots for users
  • D: Deaf – TODO
  • M: HTTP Monitor – Monitors HTTP
  • N: NetAdmin – Sends RAW IRC messages. Be very afraid
  • N: ProxyBridge – Reloading Proxybridge’s config information
  • N: UIDfix – Fixing modules’ UIDs, low-level scary scary