twisted.words.protocols.irc.IRCClient(basic.LineReceiver)
class documentationtwisted.words.protocols.irc
View Source
(View In Hierarchy)
Known subclasses: twisted.words.im.ircsupport.IRCProto
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.
Instance Variable | nickname | Nickname the client will use. |
Instance Variable | password | Password used to log on to the server. May be None . |
Instance Variable | realname | Supplied to the server during login as the "Real name" or
"ircname". May be None . |
Instance Variable | username | Supplied to the server during login as the "User name". May be None |
Instance Variable | 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)." |
Instance Variable | fingerReply | Sent in reply to a FINGER CTCP query. If None ,
no FINGER reply will be sent. (type: Callable or String) |
Instance Variable | versionName | CTCP VERSION reply, client name. If None ,
no VERSION reply will be sent. (type: str , or None.) |
Instance Variable | versionNum | CTCP VERSION reply, client version. (type: str , or None.) |
Instance Variable | versionEnv | CTCP VERSION reply, environment the client is running in. (type: str , or None.) |
Instance Variable | sourceURL | CTCP SOURCE reply, a URL where the source code of this client may be found.
If None ,
no SOURCE reply will be sent. |
Instance Variable | lineRate | Minimum delay between lines sent to the server. If None ,
no delay will be imposed. (type: Number of Seconds.) |
Instance Variable | motd | Either None
or, between receipt of RPL_MOTDSTART and RPL_ENDOFMOTD, a list
of str ,
each of which is the content of an RPL_MOTD message. |
Instance Variable | erroneousNickFallback | Default nickname assigned when an unregistered client triggers an
ERR_ERRONEUSNICKNAME while trying to register with an illegal
nickname. (type: str ) |
Instance Variable | supported | Available ISUPPORT features on the server (type: ServerSupportedFeatures ) |
Instance Variable | hostname | Host name of the IRC server the client is connected to. Initially the host
name is None
and later is set to the host name from which the RPL_WELCOME message
is received. (type: str ) |
Instance Variable | heartbeatInterval | Interval, in seconds, to send PING messages to the server as a form
of keepalive, defaults to 120 seconds. Use None
to disable the heartbeat. (type: float ) |
Method | sendLine | Sends a line to the other end of the connection. |
Method | connectionLost | Called when the connection is shut down. |
Method | stopHeartbeat | Stop sending PING messages to keep the connection to the server alive. |
Method | startHeartbeat | Start sending PING messages every IRCClient.heartbeatInterval
seconds to keep the connection to the server alive during periods of no
activity. |
Method | created | Called with creation date information about the server, usually at logon. |
Method | yourHost | Called with daemon information about the server, usually at logon. |
Method | myInfo | Called with information about the server, usually at logon. |
Method | luserClient | Called with information about the number of connections, usually at logon. |
Method | bounce | Called with information about where the client should reconnect. |
Method | isupport | Called with various information about what the server supports. |
Method | luserChannels | Called with the number of channels existent on the server. |
Method | luserOp | Called with the number of ops logged on to the server. |
Method | luserMe | Called with information about the server connected to. |
Method | privmsg | Called when I have a message from a user to me or a channel. |
Method | joined | Called when I finish joining a channel. |
Method | left | Called when I have left a channel. |
Method | noticed | Called when I have a notice from a user to me or a channel. |
Method | modeChanged | Called when users or channel's modes are changed. |
Method | pong | Called with the results of a CTCP PING query. |
Method | signedOn | Called after successfully signing on to the server. |
Method | kickedFrom | Called when I am kicked from a channel. |
Method | nickChanged | Called when my nick has been changed. |
Method | userJoined | Called when I see another user joining a channel. |
Method | userLeft | Called when I see another user leaving a channel. |
Method | userQuit | Called when I see another user disconnect from the network. |
Method | userKicked | Called when I observe someone else being kicked from a channel. |
Method | action | Called when I see a user perform an ACTION on a channel. |
Method | topicUpdated | In channel, user changed the topic to newTopic. |
Method | userRenamed | A user changed their name from oldname to newname. |
Method | receivedMOTD | I received a message-of-the-day banner from the server. |
Method | join | Join a channel. |
Method | leave | Leave a channel. |
Method | kick | Attempt to kick a user from a channel. |
Method | invite | Attempt to invite user to channel |
Method | topic | Attempt to set the topic of the given channel, or ask what it is. |
Method | mode | Change the modes on a user or channel. |
Method | say | Send a message to a channel |
Method | msg | Send a message to a user or channel. |
Method | notice | Send a notice to a user. |
Method | away | Mark this client as away. |
Method | back | Clear the away status. |
Method | whois | Retrieve user information about the given nickname. |
Method | register | Login to the server. |
Method | setNick | Set this client's nickname. |
Method | quit | Disconnect from the server |
Method | describe | Strike a pose. |
Method | ping | Measure round-trip delay to another IRC client. |
Method | dccSend | This is supposed to send a user a file directly. This generally doesn't work on any client, and this method is included only for backwards compatibility and completeness. |
Method | dccResume | Send a DCC RESUME request to another user. |
Method | dccAcceptResume | Send a DCC ACCEPT response to clients who have requested a resume. |
Method | irc_ERR_NICKNAMEINUSE | Called when we try to register or change to a nickname that is already taken. |
Method | alterCollidedNick | Generate an altered version of a nickname that caused a collision in an effort to create an unused related name for subsequent registration. |
Method | irc_ERR_ERRONEUSNICKNAME | Called when we try to register or change to an illegal nickname. |
Method | irc_ERR_PASSWDMISMATCH | Called when the login was incorrect. |
Method | irc_RPL_WELCOME | Called when we have received the welcome from the server. |
Method | irc_JOIN | Called when a user joins a channel. |
Method | irc_PART | Called when a user leaves a channel. |
Method | irc_QUIT | Called when a user has quit. |
Method | irc_MODE | Parse a server mode change message. |
Method | irc_PING | Called when some has pinged us. |
Method | irc_PRIVMSG | Called when we get a message. |
Method | irc_NOTICE | Called when a user gets a notice. |
Method | irc_NICK | Called when a user changes their nickname. |
Method | irc_KICK | Called when a user is kicked from a channel. |
Method | irc_TOPIC | Someone in the channel set the topic. |
Method | irc_RPL_TOPIC | Called when the topic for a channel is initially reported or when it subsequently changes. |
Method | irc_RPL_NOTOPIC | Undocumented |
Method | irc_RPL_MOTDSTART | Undocumented |
Method | irc_RPL_MOTD | Undocumented |
Method | irc_RPL_ENDOFMOTD | RPL_ENDOFMOTD indicates the end of the message of the day
messages. Deliver the accumulated lines to receivedMOTD . |
Method | irc_RPL_CREATED | Undocumented |
Method | irc_RPL_YOURHOST | Undocumented |
Method | irc_RPL_MYINFO | Undocumented |
Method | irc_RPL_BOUNCE | Undocumented |
Method | irc_RPL_ISUPPORT | Undocumented |
Method | irc_RPL_LUSERCLIENT | Undocumented |
Method | irc_RPL_LUSEROP | Undocumented |
Method | irc_RPL_LUSERCHANNELS | Undocumented |
Method | irc_RPL_LUSERME | Undocumented |
Method | irc_unknown | Undocumented |
Method | ctcpQuery | Dispatch method for any CTCP queries received. |
Method | ctcpUnknownQuery | Fallback handler for unrecognized CTCP queries. |
Method | ctcpQuery_ACTION | Undocumented |
Method | ctcpQuery_PING | Undocumented |
Method | ctcpQuery_FINGER | Undocumented |
Method | ctcpQuery_VERSION | Undocumented |
Method | ctcpQuery_SOURCE | Undocumented |
Method | ctcpQuery_USERINFO | Undocumented |
Method | ctcpQuery_CLIENTINFO | A master index of what CTCP tags this client knows. |
Method | ctcpQuery_ERRMSG | Undocumented |
Method | ctcpQuery_TIME | Undocumented |
Method | ctcpQuery_DCC | Initiate a Direct Client Connection |
Method | dcc_SEND | Undocumented |
Method | dcc_ACCEPT | Undocumented |
Method | dcc_RESUME | Undocumented |
Method | dcc_CHAT | Undocumented |
Method | dccDoSend | Called when I receive a DCC SEND offer from a client. |
Method | dccDoResume | 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). |
Method | dccDoAcceptResume | Called when a client has verified and accepted a DCC resume request made by us. By default it will do nothing. |
Method | dccDoChat | Undocumented |
Method | ctcpMakeReply | Send one or more extended messages as a CTCP reply. |
Method | ctcpMakeQuery | Send one or more extended messages as a CTCP query. |
Method | ctcpReply | Dispatch method for any CTCP replies received. |
Method | ctcpReply_PING | Undocumented |
Method | ctcpUnknownReply | Called when a fitting ctcpReply_ method is not found. |
Method | badMessage | When I get a message that's so broken I can't use it. |
Method | quirkyMessage | This is called when I receive a message which is peculiar, but not wholly indecipherable. |
Method | connectionMade | Called when a connection is made. |
Method | dataReceived | Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.) |
Method | lineReceived | Override this for when each line is received. |
Method | getUserModeParams | Get user modes that require parameters for correct parsing. |
Method | getChannelModeParams | Get channel modes that require parameters for correct parsing. |
Method | handleCommand | Determine the function to call for the given command and call it with the given arguments. |
Method | __getstate__ | Undocumented |
Instance Variable | _registered | Whether or not the user is registered. It becomes True once a welcome has
been received from the server. (type: bool ) |
Instance Variable | _attemptedNick | The nickname that will try to get registered. It may change if it is
illegal or already taken. nickname
becomes the _attemptedNick
that is successfully registered. (type: str ) |
Instance Variable | _heartbeat | Looping call to perform the keepalive by calling IRCClient._sendHeartbeat
every heartbeatInterval
seconds, or None
if there is no heartbeat. (type: task.LoopingCall ) |
Method | _reallySendLine | Undocumented |
Method | _sendLine | Undocumented |
Method | _createHeartbeat | Create the heartbeat LoopingCall . |
Method | _sendHeartbeat | Send a PING message to the IRC server as a form of keepalive. |
Method | _safeMaximumLineLength | Estimate a safe maximum line length for the given command. |
Inherited from LineReceiver:
Class Variable | delimiter | The line-ending delimiter to use. By default this is b'\r\n' . |
Class Variable | MAX_LENGTH | The maximum length of a line to allow (If a sent line is longer than this, the connection is dropped). Default is 16384. |
Method | clearLineBuffer | Clear buffered data. |
Method | setLineMode | Sets the line-mode of this receiver. |
Method | setRawMode | Sets the raw mode of this receiver. Further data received will be sent to rawDataReceived rather than lineReceived. |
Method | rawDataReceived | Override this for when raw data is received. |
Method | lineLengthExceeded | Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way. |
Inherited from Protocol (via LineReceiver):
Method | logPrefix | Return a prefix matching the class name, to identify log messages related to this protocol instance. |
Inherited from BaseProtocol (via LineReceiver, Protocol):
Method | makeConnection | Make a connection to a transport and a server. |
Inherited from _PauseableMixin (via LineReceiver):
Method | pauseProducing | Undocumented |
Method | resumeProducing | Undocumented |
Method | stopProducing | Undocumented |
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)."
FINGER
CTCP query. If None
,
no FINGER reply will be sent. (type: Callable or String)
None
,
no VERSION reply will be sent. (type: str
, or None.)
None
,
no SOURCE reply will be sent.
None
,
no delay will be imposed. (type: Number of Seconds.)
ERR_ERRONEUSNICKNAME
while trying to register with an illegal
nickname. (type: str
)
bool
)
nickname
becomes the _attemptedNick
that is successfully registered. (type: str
)
None
and later is set to the host name from which the RPL_WELCOME message
is received. (type: str
)
IRCClient._sendHeartbeat
every heartbeatInterval
seconds, or None
if there is no heartbeat. (type: task.LoopingCall
)
None
to disable the heartbeat. (type: float
)
Sends a line to the other end of the connection.
Parameters | line | The line to send, not including the delimiter. (type: bytes ) |
Called when the connection is shut down.
Clear any circular references here, and any external references to this Protocol. The connection has been closed.
Stop sending PING messages to keep the connection to the server alive.
Present Since | 11.1 |
Start sending PING messages every IRCClient.heartbeatInterval
seconds to keep the connection to the server alive during periods of no
activity.
Present Since | 11.1 |
Called with creation date information about the server, usually at logon.
Parameters | when | A string describing when the server was created, probably. (type: str ) |
Called with daemon information about the server, usually at logon.
Parameters | when | A string describing what software the server is running, probably. |
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 ) |
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 ) |
Called with information about where the client should reconnect.
Parameters | info | A plaintext description of the address that should be connected to. (type: str ) |
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 ) |
Called with the number of channels existent on the server.
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 ) |
Called when I have a message from a user to me or a channel.
Called when I finish joining a channel.
channel has the starting character ('#'
,
'&'
, '!'
, or '+'
) intact.
Called when I have left a channel.
channel has the starting character ('#'
,
'&'
, '!'
, or '+'
) intact.
Called when I have a notice from a user to me or a channel.
If the client makes any automated replies, it must not do so in response to a NOTICE message, per 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.
Called when users or channel's modes are changed.
Parameters | user | The user and hostmask which instigated this change. (type: str ) |
channel | The channel where the modes are changed. If args is empty the channel for
which the modes are changing. If the changes are at server level it could
be equal to user . (type: str ) | |
set | True if the mode(s) is being added, False if it is being removed. If some
modes are added and others removed at the same time this function will be
called twice, the first time with all the added modes, the second with the
removed ones. (To change this behaviour override the irc_MODE method) (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 ) |
Called when I am kicked from a channel.
Called when I see another user disconnect from the network.
Called when I observe someone else being kicked from a channel.
Called when I see a user perform an ACTION on a channel.
In channel, user changed the topic to newTopic.
Also called when first joining a channel.
A user changed their name from oldname to newname.
I received a message-of-the-day banner from the server.
motd is a list of strings, where each string was sent as a separate message from the server. To display, you might want to use:
'\n'.join(motd)
to get a nicely formatted string.
Join a channel.
Parameters | channel | The name of the channel to join. If it has no prefix, '#' will
be prepended to it. (type: str ) |
key | If specified, the key used to join the channel. (type: str ) |
Leave a channel.
Parameters | channel | The name of the channel to leave. If it has no prefix, '#'
will be prepended to it. (type: str ) |
reason | If given, the reason for leaving. (type: str ) |
Attempt to kick a user from a channel.
Parameters | channel | The name of the channel to kick the user from. If it has no prefix,
'#' will be prepended to it. (type: str ) |
user | The nick of the user to kick. (type: str ) | |
reason | If given, the reason for kicking the user. (type: str ) |
Attempt to invite user to channel
Parameters | user | The user to invite (type: str ) |
channel | The channel to invite the user too (type: str ) | |
Present Since | 11.0 |
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.
Parameters | channel | The name of the channel to change the topic on. If it has no prefix,
'#' will be prepended to it. (type: str ) |
topic | If specified, what to set the topic to. (type: str ) |
Change the modes on a user or channel.
The limit
, user
, and mask
parameters are mutually exclusive.
Parameters | chan | The name of the channel to operate on. (type: str ) |
set | True to give the user or channel permissions and False to remove them. (type: bool ) | |
modes | The mode flags to set on the user or channel. (type: str ) | |
limit | In conjunction with the 'l' mode flag, limits the number of
users on the channel. (type: int ) | |
user | The user to change the mode on. (type: str ) | |
mask | In conjunction with the 'b' mode flag, sets a mask of users to
be banned from the channel. (type: str ) |
Send a message to a channel
Parameters | channel | The channel to say the message on. If it has no prefix, '#'
will be prepended to it. (type: str ) |
message | The message to say. (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 ) |
Estimate a safe maximum line length for the given command.
This is done by assuming the maximum values for nickname length, realname and hostname combined with the command that needs to be sent and some guessing. A theoretical maximum value is used because it is possible that our nickname, username or hostname changes (on the server side) while the length is still being calculated.
Send a message to a user or channel.
The message will be split into multiple commands to the server if:
Parameters | user | Username or channel name to which to direct the message. (type: str ) |
message | Text to send. (type: str ) | |
length | Maximum number of octets to send in a single command, including the IRC
protocol framing. If None
is given then IRCClient._safeMaximumLineLength
is used to determine a value. (type: int ) |
Send a notice to a user.
Notices are like normal message, but should never get automated replies.
Parameters | user | The user to send a notice to. (type: str ) |
message | The contents of the notice to send. (type: str ) |
Mark this client as away.
Parameters | message | If specified, the away message. (type: str ) |
Retrieve user information about the given nickname.
Parameters | nickname | The nickname about which to retrieve information. (type: str ) |
Present Since | 8.2 |
Login to the server.
Parameters | nickname | The nickname to register. (type: str ) |
hostname | If specified, the hostname to logon as. (type: str ) | |
servername | If specified, the servername to logon as. (type: str ) |
Set this client's nickname.
Parameters | nickname | The nickname to change to. (type: str ) |
Disconnect from the server
Parameters | message | If specified, the message to give when quitting the server. (type: str ) |
Strike a pose.
Parameters | channel | The name of the channel to have an action on. If it has no prefix, it is
sent to the user of that name. (type: str ) |
action | The action to preform. (type: str ) | |
Present Since | 9.0 |
This is supposed to send a user a file directly. This generally doesn't work on any client, and this method is included only for backwards compatibility and completeness.
Parameters | user | str representing the user |
file | an open file (unknown, since this is not implemented) |
Send a DCC RESUME request to another user.
Send a DCC ACCEPT response to clients who have requested a resume.
Called when we try to register or change to a nickname that is already taken.
Generate an altered version of a nickname that caused a collision in an effort to create an unused related name for subsequent registration.
Parameters | nickname | The nickname a user is attempting to register. (type: str ) |
Returns | A string that is in some way different from the nickname. (type: str ) |
Called when we try to register or change to an illegal nickname.
The server should send this reply when the nickname contains any disallowed characters. The bot will stall, waiting for RPL_WELCOME, if we don't handle this during sign-on.
Note | The method uses the spelling erroneus, as it appears in the RFC, section 6.1. |
Called when we have received the welcome from the server.
Called when a user joins a channel.
Called when a user leaves a channel.
Called when a user has quit.
Called when a user changes their nickname.
Someone in the channel set the topic.
Called when the topic for a channel is initially reported or when it subsequently changes.
RPL_ENDOFMOTD indicates the end of the message of the day
messages. Deliver the accumulated lines to receivedMOTD
.
Dispatch method for any CTCP queries received.
Duplicated CTCP queries are ignored and no dispatch is made.
Unrecognized CTCP queries invoke IRCClient.ctcpUnknownQuery
.
Fallback handler for unrecognized CTCP queries.
No CTCP ERRMSG reply is made to remove a potential denial of service avenue.
A master index of what CTCP tags this client knows.
If no arguments are provided, respond with a list of known tags, sorted in alphabetical order. If an argument is provided, provide human-readable help on the usage of that tag.
Called when I receive a DCC SEND offer from a client.
By default, I do nothing here.
Parameters | user | The hostmask of the requesting user. (type: bytes ) |
address | The IP address of the requesting user. (type: bytes ) | |
port | An integer representing the port of the requesting user. (type: int ) | |
fileName | The name of the file to be transferred. (type: bytes ) | |
size | The size of the file to be transferred, which may be -1 if the
size of the file was not specified in the DCC SEND request. (type: int ) | |
data | A 3-list of [fileName, address, port]. (type: list ) |
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).
Parameters | user | The hostmask of the user who wants to resume the transfer of a file
previously offered via DCC send. (type: bytes ) |
file | The name of the file to resume the transfer of. (type: bytes ) | |
port | An integer representing the port of the requesting user. (type: int ) | |
resumePos | The position in the file from where the transfer should resume. (type: int ) |
Called when a client has verified and accepted a DCC resume request made by us. By default it will do nothing.
Parameters | user | The hostmask of the user who has accepted the DCC resume request. (type: bytes ) |
file | The name of the file to resume the transfer of. (type: bytes ) | |
port | An integer representing the port of the accepting user. (type: int ) | |
resumePos | The position in the file from where the transfer should resume. (type: int ) |
Send one or more extended messages
as a CTCP reply.
Send one or more extended messages
as a CTCP query.
Dispatch method for any CTCP replies received.
When I get a message that's so broken I can't use it.
Parameters | line | The indecipherable message. (type: bytes ) |
excType | The exception type of the exception raised by the message. (type: type ) | |
excValue | The exception parameter of excType or its associated value(the second
argument to raise ). (type: BaseException ) | |
tb | The Traceback as a traceback object. (type: traceback ) |
This is called when I receive a message which is peculiar, but not wholly indecipherable.
Parameters | s | The peculiar message. (type: bytes ) |
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.
Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.)
Override this for when each line is received.
Parameters | line | The line which was received with the delimiter removed. (type: bytes ) |
Get user modes that require parameters for correct parsing.
Returns | (type: [str, str] @return [add, remove] ) |
Get channel modes that require parameters for correct parsing.
Returns | (type: [str, str] @return [add, remove] ) |
Determine the function to call for the given command and call it with the given arguments.
Parameters | command | The IRC command to determine the function for. (type: bytes ) |
prefix | The prefix of the IRC message (as returned by parsemsg ). (type: bytes ) | |
params | A list of parameters to call the function with. (type: list ) |