mirror of
https://github.com/Mikaela/Limnoria.git
synced 2024-12-23 11:12:47 +01:00
Removing docs/INTERFACES since jemfinch doesn't want to update it and it's nearly useless in its current state.
This commit is contained in:
James Vega
parent
67c831820d
commit
0af94ef179
271
docs/INTERFACES
271
docs/INTERFACES
@ -1,271 +0,0 @@
|
||||
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).
|
||||
Loading…
Reference in New Issue
Block a user