These are the interfaces for some of the objects you'll deal with if you code for Supybot. ircmsgs.IrcMsg: This is the object that represents an IRC message. It has several methods and attributes. The most important thing about this class, however, is that it *is* hashable, and thus *cannot* be modified. Do not change any attributes; any code that modifies an IRC message is *broken* and should not exist. Interesting Methods: __init__: One of the more complex initializers in a class. It can be used in three different ways: 1) It can be given a string, as one received from the server, which it will then parse into its separate components and instantiate the class with those components as attributes. 2) It can be given a command, some (optional) arguments, and a (optional) prefix, and will instantiate the class with those components as attributes. 3) It can be given, in addition to any of the above arguments, a 'msg' keyword argument that will use the attributes of msg as defaults. This exists to make it easier to copy messages, since the class is immutable. __str__: This returns the message in a string form suitable for sending to a server. __repr__: This returns the message in a form suitable for eval(), assuming the name "IrcMsg" is in your namespace and is bound to this class. Interesting Attributes: This is the meat of this class. These are generally what you'll be looking at with IrcMsgs. command: This is the command of the IrcMsg -- PRIVMSG, NOTICE, WHOIS, etc. args: This is a tuple of the arguments to the IrcMsg. Some messages have arguments, some don't, depending on what command they are. You are, of course, always assured that args exists and is a tuple, though it might be empty. prefix: This is the hostmask of the person/server the message is from. In general, you won't be setting this on your outgoing messages, but incoming messages will always have one. This is the whole hostmask; if the message was received from a server, it'll be the server's hostmask; if the message was received from a user, it'll be the whole user hostmask. In that case, however, it's also parsed out into the nick/user/host attributes, which are probably more useful to check for many purposes. nick: If the message was sent by a user, this will be the nick of the user. If it was sent by a server, this will be the server's name (something like calvino.freenode.net or similar). user: If the message was sent by a user, this will be the user string of the user -- what they put into their IRC client for their "full name." If it was sent by a server, it'll be the server's name, again. host: If the message was sent by a user, this will be the host portion of their hostmask. If it was sent by a server, it'll be the server's name (yet again :)) irclib.Irc: This is the object to handle everything about IRC except the actual connection to the server itself. (*NOTE* that the object actually received by commands in subclasses of callbacks.Privmsg is an IrcObjectProxy, which is described later. It augments the following interface with several methods of its own to help plugin authors.) Interesting Methods: The two following messages (queueMsg and sendMsg) are the methods by far most commonly called by plugin authors. They're generally the only methods you need to pay attention to if you're writing plugins. queueMsg: Queues a message for sending to the server. The queue is generally FIFO, but it does prioritize messages based on their command. sendMsg: Queues a message for sending to the server prior to any messages in the normal queue. This is exactly a FIFO queue, no reordering is done at all. The following two methods are the most important for people writing new IrcDrivers. Otherwise, you really don't need to pay attention to them. feedMsg: Feeds the Irc object a message for it handle appropriately, as well as passing it on to callbacks. takeMsg: If the Irc object has a message it's ready to send to the server, this will return it. Otherwise, it will return None. The next several methods are of far more marginal utility. But someone may need them, so they're documented here. addCallback: Takes a callback to add to the list of callbacks in the Irc object. See the interface for IrcCallback for more information. getCallback: Gets a callback by name, if it is in the Irc object's list of callbacks. If it it isn't, returns None. removeCallback: Removes a callback by name. Returns a list of the callbacks removed (since it is technically possible to have multiple callbacks with the same name. This list may be empty. __init__: Requires a nick. Optional arguments include user and ident, which default to the nick given, password, which defaults to the empty password, and callbacks, a list of callbacks (which defaults to nothing, an empty list). reset: Resets the Irc object to its original state, as well as sends a reset() to every callbacks. die: Kills the IRC object and all its callbacks. Interesting attributes: nick: The current nick of the bot. prefix: The current prefix of the bot. server: The current server the bot is connected to. network: The current network name the bot is connected to. afterConnect: False until the bot has received a command sent after the connection is finished -- 376, 377, or 422. state: An IrcState object for this particular connection. See the interface for the IrcState object for more information. irclib.IrcCallback: Interesting Methods: name: Returns the name of the callback. The default implementation simply returns the name of the class. __call__: Called by the Irc object with itself and the message whenever a message is fed to the Irc object. Nothing is done with the return value. inFilter: Called by the Irc object with itself and the message whenever a message is fed to the Irc object. The return value should be an IrcMsg object to be passed to the next callback in the Irc's list of callbacks. If None is returned, all processing stops. This gives callbacks an oppurtunity to "filter" incoming messages before general callbacks are given them. outFilter: Basically equivalent to inFilter, except instead of being called on messages as they enter the Irc object, it's called on messages as they leave the Irc object. die: Called when the parent Irc is told to die. This gives callbacks an oppurtunity to close open files, network connections, or databases before they're deleted. reset: Called when the parent Irc is told to reset (which is generally when reconnecting to the server). Most callbacks don't need to define this. Interesting attributes: priority: Determines the priority of the callback in the Irc object's list of callbacks. Defaults to 99; the valid range includes 0 through sys.maxint-1 (don't use sys.maxint itself, that's reserved for the Misc plugin). The lower the number, the higher the priority. High priority callbacks are called earlier in the inFilter cycle, earlier in the __call__ cycle, and later in the outFilter cycle -- basically, they're given the first chances on the way in and the last chances on the way out. callbacks.IrcObjectProxy: IrcObjectProxy is a proxy for an irclib.Irc instance that serves to provide a much fuller interface for handling replies and errors as well as to handle the nesting of commands. This is what you'll be dealing with almost all the time when writing commands; when writing doCommand methods (the kind you read about in the interface description of irclib.IrcCallback) you'll be dealing with plain old irclib.Irc objects. Interesting methods: reply: Called to reply to the current message with a string that is to be the reply. replySuccess, replyError: These reply with the configured responses for success and generic error, respectively. If an additional argument is given, it's (intelligently) appended to the generic message to be more specific. error: Called to send an error reply to the current message; not only does the response indicate an error, but commands that error out break the nested-command chain, which is generally useful for not confusing the user :) errorNoCapability: Like error, except it accepts the capability that's missing and integrates it into the configured error message for such things. Also accepts an additional string for a more descriptive message, if that's what you want. errorPossibleBug, errorNotRegistered, errorNoUser, errorRequiresPrivacy: These methods reply with the appropriate configured error message for the conditions in their names; they all take an additional arguments to be more specific about the conditions they indicate, but this argument is very rarely necessary. getRealIrc: Returns the actual Irc object being proxied for. replies: Sends a collection of messages to a given target, much like reply; except in this case, the user can configure whether the messages will be sent one-by-one or combined into a single message. Thus, the method accepts a "prefixer" argument, which prefixes the messages with a given string (or according to a given function), a "joiner" string (or function) used to join the messages into a single message if necessary, and an onlyPrefixFirst argument which determines whether only the first message will be prefixed when the messages are sent separately (it defaults to False).