Package twisted :: Package words :: Package protocols :: Module irc :: Class IRCClient

Class IRCClient

BaseProtocol --+        
               |        
        Protocol --+    
                   |    
 _PauseableMixin --+    
                   |    
        LineReceiver --+
                       |
                      IRCClient

Known Subclasses:: IrcStatusBot

Internet Relay Chat client protocol, with sprinkles.

In addition to providing an interface for an IRC client protocol, this class also contains reasonable implementations of many common CTCP methods.

TODO

Limit the length of messages sent (because the IRC server probably does).
Add flood protection/rate limiting for my CTCP replies.
NickServ cooperation. (a mix-in?)
Heartbeat. The transport may die in such a way that it does not realize it is dead until it is written to. Sending something (like "PING this.irc-host.net") during idle peroids would alleviate that. If you're concerned with the stability of the host as well as that of the transport, you might care to watch for the corresponding PONG.

Method Summary
	`__getstate__(self)`
	`action(self, user, channel, data)` Called when I see a user perform an ACTION on a channel.
	`away(self, message)`
	`badMessage(self, line, excType, excValue, tb)` When I get a message that's so broken I can't use it.
	`bounce(self, info)` Called with information about where the client should reconnect.
	`connectionMade(self)` Called when a connection is made.
	`created(self, when)` Called with creation date information about the server, usually at logon.
	`ctcpMakeQuery(self, user, messages)` Send one or more extended messages as a CTCP query.
	`ctcpMakeReply(self, user, messages)` Send one or more extended messages as a CTCP reply.
	`ctcpQuery(self, user, channel, messages)` Dispatch method for any CTCP queries received.
	`ctcpQuery_ACTION(self, user, channel, data)`
	`ctcpQuery_CLIENTINFO(self, user, channel, data)` A master index of what CTCP tags this client knows.
	`ctcpQuery_DCC(self, user, channel, data)` Initiate a Direct Client Connection
	`ctcpQuery_ERRMSG(self, user, channel, data)`
	`ctcpQuery_FINGER(self, user, channel, data)`
	`ctcpQuery_PING(self, user, channel, data)`
	`ctcpQuery_SOURCE(self, user, channel, data)`
	`ctcpQuery_TIME(self, user, channel, data)`
	`ctcpQuery_USERINFO(self, user, channel, data)`
	`ctcpQuery_VERSION(self, user, channel, data)`
	`ctcpReply(self, user, channel, messages)` Dispatch method for any CTCP replies received.
	`ctcpReply_PING(self, user, channel, data)`
	`ctcpUnknownQuery(self, user, channel, tag, data)`
	`ctcpUnknownReply(self, user, channel, tag, data)` Called when a fitting ctcpReply_ method is not found.
	`dataReceived(self, data)` Protocol.dataReceived.
	`dcc_ACCEPT(self, user, channel, data)`
	`dcc_CHAT(self, user, channel, data)`
	`dcc_RESUME(self, user, channel, data)`
	`dcc_SEND(self, user, channel, data)`
	`dccAcceptResume(self, user, fileName, port, resumePos)` Send a DCC ACCEPT response to clients who have requested a resume.
	`dccDoAcceptResume(self, user, file, port, resumePos)` Called when a client has verified and accepted a DCC resume request made by us.
	`dccDoChat(self, user, channel, address, port, data)`
	`dccDoResume(self, user, file, port, resumePos)` Called when a client is trying to resume an offered file via DCC send.
	`dccDoSend(self, user, address, port, fileName, size, data)` Called when I receive a DCC SEND offer from a client.
	`dccResume(self, user, fileName, port, resumePos)` Send a DCC RESUME request to another user.
	`dccSend(self, user, file)`
	`handleCommand(self, command, prefix, params)` Determine the function to call for the given command and call it with the given arguments.
	`irc_ERR_NICKNAMEINUSE(self, prefix, params)`
	`irc_ERR_PASSWDMISMATCH(self, prefix, params)`
	`irc_JOIN(self, prefix, params)`
	`irc_KICK(self, prefix, params)` Kicked? Who? Not me, I hope.
	`irc_MODE(self, prefix, params)`
	`irc_NICK(self, prefix, params)`
	`irc_NOTICE(self, prefix, params)`
	`irc_PART(self, prefix, params)`
	`irc_PING(self, prefix, params)`
	`irc_PRIVMSG(self, prefix, params)`
	`irc_QUIT(self, prefix, params)`
	`irc_RPL_BOUNCE(self, prefix, params)`
	`irc_RPL_CREATED(self, prefix, params)`
	`irc_RPL_ENDOFMOTD(self, prefix, params)`
	`irc_RPL_LUSERCHANNELS(self, prefix, params)`
	`irc_RPL_LUSERCLIENT(self, prefix, params)`
	`irc_RPL_LUSERME(self, prefix, params)`
	`irc_RPL_LUSEROP(self, prefix, params)`
	`irc_RPL_MOTD(self, prefix, params)`
	`irc_RPL_MOTDSTART(self, prefix, params)`
	`irc_RPL_MYINFO(self, prefix, params)`
	`irc_RPL_NOTOPIC(self, prefix, params)`
	`irc_RPL_TOPIC(self, prefix, params)` I just joined the channel, and the server is telling me the current topic.
	`irc_RPL_WELCOME(self, prefix, params)`
	`irc_RPL_YOURHOST(self, prefix, params)`
	`irc_TOPIC(self, prefix, params)` Someone in the channel set the topic.
	`irc_unknown(self, prefix, command, params)`
	`isupport(self, options)` Called with various information about what the server supports.
	`join(self, channel, key)`
	`joined(self, channel)` Called when I finish joining a channel.
	`kick(self, channel, user, reason)`
	`kickedFrom(self, channel, kicker, message)` Called when I am kicked from a channel.
	`leave(self, channel, reason)`
	`left(self, channel)` Called when I have left a channel.
	`lineReceived(self, line)` Override this for when each line is received.
	`luserChannels(self, channels)` Called with the number of channels existant on the server.
	`luserClient(self, info)` Called with information about the number of connections, usually at logon.
	`luserMe(self, info)` Called with information about the server connected to.
	`luserOp(self, ops)` Called with the number of ops logged on to the server.
	`me(self, channel, action)` Strike a pose.
	`mode(self, chan, set, modes, limit, user, mask)` Change the modes on a user or channel.
	`modeChanged(self, user, channel, set, modes, args)` Called when a channel's modes are changed
	`msg(self, user, message, length)` Send a message to a user or channel.
	`myInfo(self, servername, version, umodes, cmodes)` Called with information about the server, usually at logon.
	`nickChanged(self, nick)` Called when my nick has been changed.
	`notice(self, user, message)`
	`noticed(self, user, channel, message)` Called when I have a notice from a user to me or a channel.
	`part(self, channel, reason)`
	`ping(self, user, text)` Measure round-trip delay to another IRC client.
	`pong(self, user, secs)` Called with the results of a CTCP PING query.
	`privmsg(self, user, channel, message)` Called when I have a message from a user to me or a channel.
	`quirkyMessage(self, s)` This is called when I receive a message which is peculiar, but not wholly indecipherable.
	`quit(self, message)`
	`receivedMOTD(self, motd)` I received a message-of-the-day banner from the server.
	`register(self, nickname, hostname, servername)`
	`say(self, channel, message, length)`
	`sendLine(self, line)` Sends a line to the other end of the connection.
	`setNick(self, nickname)`
	`signedOn(self)` Called after sucessfully signing on to the server.
	`topic(self, channel, topic)` Attempt to set the topic of the given channel, or ask what it is.
	`topicUpdated(self, user, channel, newTopic)` In channel, user changed the topic to newTopic.
	`userJoined(self, user, channel)` Called when I see another user joining a channel.
	`userKicked(self, kickee, channel, kicker, message)` Called when I observe someone else being kicked from a channel.
	`userLeft(self, user, channel)` Called when I see another user leaving a channel.
	`userQuit(self, user, quitMessage)` Called when I see another user disconnect from the network.
	`userRenamed(self, oldname, newname)` A user changed their name from oldname to newname.
	`yourHost(self, info)` Called with daemon information about the server, usually at logon.
Inherited from LineReceiver
	`clearLineBuffer(self)` Clear buffered data.
	`lineLengthExceeded(self, line)` Called when the maximum line length has been reached.
	`rawDataReceived(self, data)` Override this for when raw data is received.
	`setLineMode(self, extra)` Sets the line-mode of this receiver.
	`setRawMode(self)` Sets the raw mode of this receiver.
Inherited from Protocol
	`connectionLost(self, reason)` Called when the connection is shut down.

Instance Variable Summary
Callable or String	`fingerReply`: Sent in reply to a FINGER CTCP query.
Number of Seconds.	`lineRate`: Minimum delay between lines sent to the server.
`str`	`nickname`: Nickname the client will use.
`NoneType`	`password`: Password used to log on to the server.
`NoneType`	`realname`: Supplied to the server during login as the "Real name" or "ircname".
`str`	`sourceURL`: CTCP SOURCE reply, a URL where the source code of this client may be found.
`NoneType`	`userinfo`: Sent in reply to a USERINFO CTCP query.
`NoneType`	`username`: Supplied to the server during login as the "User name".
`NoneType`	`versionEnv`: CTCP VERSION reply, environment the client is running in.
`NoneType`	`versionName`: CTCP VERSION reply, client name.
`NoneType`	`versionNum`: CTCP VERSION reply, client version,

Class Variable Summary
`str`	`__pychecker__` = `'unusednames=params,prefix,channel'`
`str`	`dcc_destdir` = `'.'`
`NoneType`	`dcc_sessions` = None
`str`	`delimiter`: The line-ending delimiter to use.
`str`	`motd` = `''`
`int`	`performLogin` = 1
Inherited from LineReceiver
`int`	`line_mode` = 1
`int`	`MAX_LENGTH`: The maximum length of a line to allow (If a sent line is longer than this, the connection is dropped).
Inherited from Protocol
`Implements`	`__implemented__` = `<implementedBy twisted.internet.protoc...`
`ClassProvides`	`__provides__` = `<zope.interface.declarations.ClassProvide...`

Method Details

action(self, user, channel, data)

Called when I see a user perform an ACTION on a channel.

badMessage(self, line, excType, excValue, tb)

When I get a message that's so broken I can't use it.

bounce(self, info)

Called with information about where the client should reconnect.

Parameters:: info - A plaintext description of the address that should be connected to.
(type=str)

connectionMade(self)

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

Overrides:: twisted.internet.protocol.BaseProtocol.connectionMade (inherited documentation)

created(self, when)

Called with creation date information about the server, usually at logon.

Parameters:: when - A string describing when the server was created, probably.
(type=str)

ctcpMakeQuery(self, user, messages)

Send one or more extended messages as a CTCP query.

Parameters:: messages
(type=a list of extended messages. An extended message is a (tag, data) tuple, where 'data' may be None.)

ctcpMakeReply(self, user, messages)

Send one or more extended messages as a CTCP reply.

Parameters:: messages
(type=a list of extended messages. An extended message is a (tag, data) tuple, where 'data' may be None.)

ctcpQuery(self, user, channel, messages)

Dispatch method for any CTCP queries received.

ctcpQuery_CLIENTINFO(self, user, channel, data)

A master index of what CTCP tags this client knows.

If no arguments are provided, respond with a list of known tags. If an argument is provided, provide human-readable help on the usage of that tag.

ctcpQuery_DCC(self, user, channel, data)

Initiate a Direct Client Connection

ctcpReply(self, user, channel, messages)

Dispatch method for any CTCP replies received.

ctcpUnknownReply(self, user, channel, tag, data)

Called when a fitting ctcpReply_ method is not found.

XXX: If the client makes arbitrary CTCP queries, this method should probably show the responses to them instead of treating them as anomolies.

dataReceived(self, data)

Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.)

Overrides:: twisted.protocols.basic.LineReceiver.dataReceived (inherited documentation)

dccAcceptResume(self, user, fileName, port, resumePos)

Send a DCC ACCEPT response to clients who have requested a resume.

dccDoAcceptResume(self, user, file, port, resumePos)

Called when a client has verified and accepted a DCC resume request made by us. By default it will do nothing.

dccDoResume(self, user, file, port, resumePos)

Called when a client is trying to resume an offered file via DCC send. It should be either replied to with a DCC ACCEPT or ignored (default).

dccDoSend(self, user, address, port, fileName, size, data)

Called when I receive a DCC SEND offer from a client.

By default, I do nothing here.

dccResume(self, user, fileName, port, resumePos)

Send a DCC RESUME request to another user.

handleCommand(self, command, prefix, params)

Determine the function to call for the given command and call it with the given arguments.

irc_KICK(self, prefix, params)

Kicked? Who? Not me, I hope.

irc_RPL_TOPIC(self, prefix, params)

I just joined the channel, and the server is telling me the current topic.

irc_TOPIC(self, prefix, params)

Someone in the channel set the topic.

isupport(self, options)

Called with various information about what the server supports.

Parameters:: options - Descriptions of features or limits of the server, possibly in the form "NAME=VALUE".
(type=list of str)

joined(self, channel)

Called when I finish joining a channel.

channel has the starting character (# or &) intact.

kickedFrom(self, channel, kicker, message)

Called when I am kicked from a channel.

left(self, channel)

Called when I have left a channel.

channel has the starting character (# or &) intact.

lineReceived(self, line)

Override this for when each line is received.

Overrides:: twisted.protocols.basic.LineReceiver.lineReceived (inherited documentation)

luserChannels(self, channels)

Called with the number of channels existant on the server.

Parameters:: channels
(type=int)

luserClient(self, info)

Called with information about the number of connections, usually at logon.

Parameters:: info - A description of the number of clients and servers connected to the network, probably.
(type=str)

luserMe(self, info)

Called with information about the server connected to.

Parameters:: info - A plaintext string describing the number of users and servers connected to this server.
(type=str)

luserOp(self, ops)

Called with the number of ops logged on to the server.

Parameters:: ops
(type=int)

me(self, channel, action)

Strike a pose.

mode(self, chan, set, modes, limit=None, user=None, mask=None)

Change the modes on a user or channel.

modeChanged(self, user, channel, set, modes, args)

Called when a channel's modes are changed

Parameters:: user - The user and hostmask which instigated this change.
(type=str); channel - The channel for which the modes are changing.
(type=str); set - true if the mode is being added, false if it is being removed.
(type=bool or int); modes - The mode or modes which are being changed.
(type=str); args - Any additional information required for the mode change.
(type=tuple)

msg(self, user, message, length=None)

Send a message to a user or channel.

Parameters:: user - The username or channel name to which to direct the message.
(type=str); message - The text to send
(type=str); length - The maximum number of octets to send at a time. This has the effect of turning a single call to msg() into multiple commands to the server. This is useful when long messages may be sent that would otherwise cause the server to kick us off or silently truncate the text we are sending. If None is passed, the entire message is always send in one command.
(type=int)

myInfo(self, servername, version, umodes, cmodes)

Called with information about the server, usually at logon.

Parameters:: servername - The hostname of this server.
(type=str); version - A description of what software this server runs.
(type=str); umodes - All the available user modes.
(type=str); cmodes - All the available channel modes.
(type=str)

nickChanged(self, nick)

Called when my nick has been changed.

noticed(self, user, channel, message)

Called when I have a notice from a user to me or a channel.

By default, this is equivalent to IRCClient.privmsg, but if your client makes any automated replies, you must override this! From the RFC:

   The difference between NOTICE and PRIVMSG is that
   automatic replies MUST NEVER be sent in response to a
   NOTICE message. [...] The object of this rule is to avoid
   loops between clients automatically sending something in
   response to something it received.

ping(self, user, text=None)

Measure round-trip delay to another IRC client.

pong(self, user, secs)

Called with the results of a CTCP PING query.

privmsg(self, user, channel, message)

Called when I have a message from a user to me or a channel.

quirkyMessage(self, s)

This is called when I receive a message which is peculiar, but not wholly indecipherable.

receivedMOTD(self, motd)

I received a message-of-the-day banner from the server.

motd is a list of strings, where each string was sent as a seperate message from the server. To display, you might want to use:

   string.join(motd, '\n')

to get a nicely formatted string.

sendLine(self, line)

Sends a line to the other end of the connection.

Overrides:: twisted.protocols.basic.LineReceiver.sendLine (inherited documentation)

signedOn(self)

Called after sucessfully signing on to the server.

topic(self, channel, topic=None)

Attempt to set the topic of the given channel, or ask what it is.

If topic is None, then I sent a topic query instead of trying to set the topic. The server should respond with a TOPIC message containing the current topic of the given channel.

topicUpdated(self, user, channel, newTopic)

In channel, user changed the topic to newTopic.

Also called when first joining a channel.

userJoined(self, user, channel)

Called when I see another user joining a channel.

userKicked(self, kickee, channel, kicker, message)

Called when I observe someone else being kicked from a channel.

userLeft(self, user, channel)

Called when I see another user leaving a channel.

userQuit(self, user, quitMessage)

Called when I see another user disconnect from the network.

userRenamed(self, oldname, newname)

A user changed their name from oldname to newname.

yourHost(self, info)

Called with daemon information about the server, usually at logon.

Parameters:: info
(type=str)

Instance Variable Details

fingerReply

Sent in reply to a FINGER CTCP query. If None, no FINGER reply will be sent.

Type:: Callable or String
Value:: None

lineRate

Minimum delay between lines sent to the server. If None, no delay will be imposed.

Type:: Number of Seconds.
Value:: None

nickname

Nickname the client will use.

Type:: str
Value:: 'irc'

password

Password used to log on to the server. May be None.

Type:: NoneType
Value:: None

realname

Supplied to the server during login as the "Real name" or "ircname". May be None.

Type:: NoneType
Value:: None

sourceURL

CTCP SOURCE reply, a URL where the source code of this client may be found. If None, no SOURCE reply will be sent.

Type:: str
Value:: 'http://twistedmatrix.com/downloads/'

userinfo

Sent in reply to a USERINFO CTCP query. If None, no USERINFO reply will be sent. "This is used to transmit a string which is settable by the user (and never should be set by the client)."

Type:: NoneType
Value:: None

username

Supplied to the server during login as the "User name". May be None

Type:: NoneType
Value:: None

versionEnv

CTCP VERSION reply, environment the client is running in.

Type:: NoneType
Value:: None

versionName

CTCP VERSION reply, client name. If None, no VERSION reply will be sent.

Type:: NoneType
Value:: None

versionNum

CTCP VERSION reply, client version,

Type:: NoneType
Value:: None

Class Variable Details

pychecker

Type:: str
Value:: 'unusednames=params,prefix,channel'

dcc_destdir

Type:: str
Value:: '.'

dcc_sessions

Type:: NoneType
Value:: None

delimiter

The line-ending delimiter to use. By default this is '\r\n'.

Type:: str
Value:: ''' '''

motd

Type:: str
Value:: ''

performLogin

Type:: int
Value:: 1

Generated by Epydoc 2.1 on Sun Dec 10 22:04:45 2006

http://epydoc.sf.net