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

[show private | hide private]
[frames | no frames]

## Class IRCClient

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

Known Subclasses:
  `IRCProto`, `TendrilIRC`

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.
| ``connectionFailed`(self)` (Deprecated) (inherited from `Protocol`)
| ``connectionLost`(self, reason)` Called when the connection is shut down. (inherited from `Protocol`)
| ``connectionMade`(self)` Called when a connection is made.
| ``ctcpMakeQuery`(self, user, messages)` Send one or more extended messagesas a CTCP query.
| ``ctcpMakeReply`(self, user, messages)` Send one or more extended messagesas 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_RPL_ENDOFMOTD(self, prefix, params)`
| `irc_RPL_MOTD(self, prefix, params)`
| `irc_RPL_MOTDSTART(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_TOPIC`(self, prefix, params)` Someone in the channel set the topic.
| `irc_unknown(self, prefix, command, params)`
| `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.
| ``lineLengthExceeded`(self, line)` Called when the maximum line length has been reached. (inherited from `LineReceiver`)
| ``lineReceived`(self, line)` Override this for when each line is received.
| ``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)`
| ``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)`
| ``rawDataReceived`(self, data)` Override this for when raw data is received. (inherited from `LineReceiver`)
| ``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.
| ``setLineMode`(self, extra)` Sets the line-mode of this receiver. (inherited from `LineReceiver`)
| `setNick(self, nickname)`
| ``setRawMode`(self)` Sets the raw mode of this receiver. (inherited from `LineReceiver`)
| ``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.
| ``userRenamed`(self, oldname, newname)` A user changed their name from oldname to newname.

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

Class Variable Summary
`str` | `__pychecker__`
`str` | `dcc_destdir`
`NoneType` | `dcc_sessions`
`str` | `delimiter`
Callable or String | `fingerReply`
Number of Seconds. | `lineRate`
`str` | `motd`
`str` | `nickname`
`NoneType` | `password`
`int` | `performLogin`
`NoneType` | `realname`
`str` | `sourceURL`
`NoneType` | `userinfo`
`NoneType` | `versionEnv`
`NoneType` | `versionName`
`NoneType` | `versionNum`

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.

### 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)

### 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.

### 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)

### 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`)

### 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.

### userRenamed(self, oldname, newname)

A user changed their name from oldname to newname.

Instance Variable Details

### fingerReply

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

### lineRate

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

### nickname

Nickname the client will use.

### password

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

### realname

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

### sourceURL

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

### 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)."

### versionEnv

CTCP VERSION reply, environment the client is running in.

### versionName

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

### versionNum

CTCP VERSION reply, client version,

Class Variable Details

### __pychecker__

  Type:
    `str`
  Value:

        'unusednames=params,prefix,channel'

### dcc_destdir

  Type:
    `str`
  Value:

        '.'

### dcc_sessions

  Type:
    `NoneType`
  Value:

        None

### delimiter

  Type:
    `str`
  Value:

        '''
        '''

### fingerReply

  Type:
    Callable or String
  Value:

        None

### lineRate

  Type:
    Number of Seconds.
  Value:

        None

### motd

  Type:
    `str`
  Value:

        ''

### nickname

  Type:
    `str`
  Value:

        'irc'

### password

  Type:
    `NoneType`
  Value:

        None

### performLogin

  Type:
    `int`
  Value:

        1

### realname

  Type:
    `NoneType`
  Value:

        None

### sourceURL

  Type:
    `str`
  Value:

        'http://twistedmatrix.com/downloads/'

### userinfo

  Type:
    `NoneType`
  Value:

        None

### versionEnv

  Type:
    `NoneType`
  Value:

        None

### versionName

  Type:
    `NoneType`
  Value:

        None

### versionNum

  Type:
    `NoneType`
  Value:

        None

Generated by Epydoc 1.1 on Thu May 8 13:16:40 2003 | http://epydoc.sf.net