irc package¶
Subpackages¶
Submodules¶
irc.bot module¶
Simple IRC bot library.
This module contains a single-server IRC bot class that can be used to write simpler bots.
- class irc.bot.Channel[source]¶
Bases:
object
A class for keeping information about an IRC channel.
- clear_mode(mode, value=None)[source]¶
Clear mode on the channel.
Arguments:
mode – The mode (a single-character string).
value – Value
- set_mode(mode, value=None)[source]¶
Set mode on the channel.
Arguments:
mode – The mode (a single-character string).
value – Value
- property user_dicts¶
- user_modes = 'ovqha'¶
Modes which are applicable to individual users, and which should be tracked in the mode_users dictionary.
- class irc.bot.ExponentialBackoff(**attrs)[source]¶
Bases:
ReconnectStrategy
A ReconnectStrategy implementing exponential backoff with jitter.
- max_interval = 300¶
- min_interval = 60¶
- class irc.bot.ReconnectStrategy[source]¶
Bases:
object
An abstract base class describing the interface used by SingleServerIRCBot for handling reconnect following disconnect events.
- class irc.bot.ServerSpec(host, port=6667, password=None)[source]¶
Bases:
object
An IRC server specification.
>>> spec = ServerSpec('localhost') >>> spec.host 'localhost' >>> spec.port 6667 >>> spec.password
>>> spec = ServerSpec('127.0.0.1', 6697, 'fooP455') >>> spec.password 'fooP455'
- class irc.bot.SingleServerIRCBot(server_list, nickname, realname, _=None, recon=ExponentialBackoff(), **connect_params)[source]¶
Bases:
SimpleIRCClient
A single-server IRC bot class.
The bot tries to reconnect if it is disconnected.
The bot keeps track of the channels it has joined, the other clients that are present in the channels and which of those that have operator or voice modes. The “database” is kept in the self.channels attribute, which is an IRCDict of Channels.
Arguments:
- server_list – A list of ServerSpec objects or tuples of
parameters suitable for constructing ServerSpec objects. Defines the list of servers the bot will use (in order).
nickname – The bot’s nickname.
realname – The bot’s realname.
- recon – A ReconnectStrategy for reconnecting on
disconnect or failed connection.
- dcc_connections – A list of initiated/accepted DCC
connections.
- **connect_params – parameters to pass through to the connect
method.
- disconnect(msg="I'll be back!")[source]¶
Disconnect the bot.
The bot will try to reconnect after a while.
Arguments:
msg – Quit message.
- jump_server(msg='Changing servers')[source]¶
Connect to a new server, possibly disconnecting from the current.
The bot will skip to next server in the server_list each time jump_server is called.
irc.client module¶
Internet Relay Chat (IRC) protocol client library.
This library is intended to encapsulate the IRC protocol in Python. It provides an event-driven IRC client framework. It has a fairly thorough support for the basic IRC protocol, CTCP, and DCC chat.
To best understand how to make an IRC client, the reader more or less must understand the IRC specifications. They are available here: [IRC specifications].
The main features of the IRC client framework are:
Abstraction of the IRC protocol.
Handles multiple simultaneous IRC server connections.
Handles server PONGing transparently.
Messages to the IRC server are done by calling methods on an IRC connection object.
Messages from an IRC server triggers events, which can be caught by event handlers.
Reading from and writing to IRC server sockets are normally done by an internal select() loop, but the select()ing may be done by an external main loop.
Functions can be registered to execute at specified times by the event-loop.
Decodes CTCP tagging correctly (hopefully); I haven’t seen any other IRC client implementation that handles the CTCP specification subtleties.
A kind of simple, single-server, object-oriented IRC client class that dispatches events to instance methods is included.
Current limitations:
Data is not written asynchronously to the server, i.e. the write() may block if the TCP buffers are stuffed.
DCC file transfers are not supported.
RFCs 2810, 2811, 2812, and 2813 have not been considered.
- Notes:
connection.quit() only sends QUIT to the server.
ERROR from the server triggers the error event and the disconnect event.
dropping of the connection triggers the disconnect event.
- class irc.client.Connection(reactor)[source]¶
Bases:
object
Base class for IRC connections.
- abstract property socket¶
The socket for this connection
- transmit_encoding = 'utf-8'¶
encoding used for transmission
- class irc.client.DCCConnection(reactor, dcctype)[source]¶
Bases:
Connection
A DCC (Direct Client Connection).
DCCConnection objects are instantiated by calling the dcc method on a Reactor object.
- connect(address, port)[source]¶
Connect/reconnect to a DCC peer.
- Arguments:
address – Host/IP address of the peer.
port – The port number to connect to.
Returns the DCCConnection object.
- connected = False¶
- disconnect(message='')[source]¶
Hang up the connection and close the object.
Arguments:
message – Quit message.
- listen(addr=None)[source]¶
Wait for a connection/reconnection from a DCC peer.
Returns the DCCConnection object.
The local IP address and port are available as self.localaddress and self.localport. After connection from a peer, the peer address and port are available as self.peeraddress and self.peerport.
- passive = False¶
- peeraddress = None¶
- peerport = None¶
- privmsg(text)[source]¶
Send text to DCC peer.
The text will be padded with a newline if it’s a DCC CHAT session.
- socket = None¶
- class irc.client.Event(type, source, target, arguments=None, tags=None)[source]¶
Bases:
object
An IRC event.
>>> print(Event('privmsg', '@somebody', '#channel')) type: privmsg, source: @somebody, target: #channel, arguments: [], tags: []
- exception irc.client.InvalidCharacters[source]¶
Bases:
ValueError
Invalid characters were encountered in the message
- exception irc.client.MessageTooLong[source]¶
Bases:
ValueError
Message is too long
- class irc.client.NickMask[source]¶
Bases:
str
A nickmask (the source of an Event)
>>> nm = NickMask('pinky!username@example.com') >>> nm.nick 'pinky'
>>> nm.host 'example.com'
>>> nm.user 'username'
>>> isinstance(nm, str) True
>>> nm = NickMask('красный!red@yahoo.ru')
>>> isinstance(nm.nick, str) True
Some messages omit the userhost. In that case, None is returned.
>>> nm = NickMask('irc.server.net') >>> nm.nick 'irc.server.net' >>> nm.userhost >>> nm.host >>> nm.user
- property host¶
- property nick¶
- property user¶
- property userhost¶
- class irc.client.Reactor(on_connect=__do_nothing, on_disconnect=__do_nothing)[source]¶
Bases:
object
Processes events from one or more IRC server connections.
This class implements a reactor in the style of the reactor pattern.
When a Reactor object has been instantiated, it can be used to create Connection objects that represent the IRC connections. The responsibility of the reactor object is to provide an event-driven framework for the connections and to keep the connections alive. It runs a select loop to poll each connection’s TCP socket and hands over the sockets with incoming data for processing by the corresponding connection.
The methods of most interest for an IRC client writer are server, add_global_handler, remove_global_handler, process_once, and process_forever.
This is functionally an event-loop which can either use it’s own internal polling loop, or tie into an external event-loop, by having the external event-system periodically call process_once on the instantiated reactor class. This will allow the reactor to process any queued data and/or events.
Calling process_forever will hand off execution to the reactor’s internal event-loop, which will not return for the life of the reactor.
Here is an example:
client = irc.client.Reactor() server = client.server() server.connect(“irc.some.where”, 6667, “my_nickname”) server.privmsg(“a_nickname”, “Hi there!”) client.process_forever()
This will connect to the IRC server irc.some.where on port 6667 using the nickname my_nickname and send the message “Hi there!” to the nickname a_nickname.
The methods of this class are thread-safe; accesses to and modifications of its internal lists of connections, handlers, and delayed commands are guarded by a mutex.
- add_global_handler(event, handler, priority=0)[source]¶
Adds a global handler function for a specific event type.
Arguments:
- event – Event type (a string). Check the values of
numeric_events for possible event types.
- handler – Callback function taking ‘connection’ and ‘event’
parameters.
priority – A number (the lower number, the higher priority).
The handler function is called whenever the specified event is triggered in any of the connections. See documentation for the Event class.
The handler functions are called in priority order (lowest number is highest priority). If a handler function returns “NO MORE”, no more handlers will be called.
- connection_class¶
alias of
ServerConnection
- dcc(dcctype='chat')[source]¶
Creates and returns a DCCConnection object.
Arguments:
- dcctype – “chat” for DCC CHAT connections or “raw” for
DCC SEND (or other DCC types). If “chat”, incoming data will be split in newline-separated chunks. If “raw”, incoming data is not touched.
- process_data(sockets)[source]¶
Called when there is more data to read on connection sockets.
Arguments:
sockets – A list of socket objects.
See documentation for Reactor.__init__.
- process_forever(timeout=0.2)[source]¶
Run an infinite loop, processing data from connections.
This method repeatedly calls process_once.
Arguments:
timeout – Parameter to pass to process_once.
- process_once(timeout=0)[source]¶
Process data from connections once.
Arguments:
- timeout – How long the select() call should wait if no
data is available.
This method should be called periodically to check and process incoming data, if there are any. If that seems boring, look at the process_forever method.
- process_timeout()[source]¶
Called when a timeout notification is due.
See documentation for Reactor.__init__.
- remove_global_handler(event, handler)[source]¶
Removes a global handler function.
Arguments:
event – Event type (a string). handler – Callback function.
Returns 1 on success, otherwise 0.
- scheduler_class¶
alias of
DefaultScheduler
- property sockets¶
- class irc.client.ServerConnection(reactor)[source]¶
Bases:
Connection
An IRC server connection.
ServerConnection objects are instantiated by calling the server method on a Reactor object.
- add_global_handler(*args)[source]¶
Add global handler.
See documentation for IRC.add_global_handler.
- buffer_class¶
alias of
DecodingLineBuffer
- cap(subcommand, *args)[source]¶
Send a CAP command according to the spec.
Arguments:
subcommand – LS, LIST, REQ, ACK, CLEAR, END args – capabilities, if required for given subcommand
Example:
.cap(‘LS’) .cap(‘REQ’, ‘multi-prefix’, ‘sasl’) .cap(‘END’)
- close()[source]¶
Close the connection.
This method closes the connection permanently; after it has been called, the object is unusable.
- connect(server: str, port: int, nickname: str, password: str | None = None, username: str | None = None, ircname: str | None = None, connect_factory=connection.Factory(), sasl_login: str | None = None)[source]¶
Connect/reconnect to a server.
Arguments:
server - Server name
port - Port number
nickname - The nickname
password - Password (if any)
username - The username
ircname - The IRC name (“realname”)
server_address - The remote host/port of the server
connect_factory - A callable that takes the server address and returns a connection (with a socket interface)
sasl_login - A string used to toggle sasl plain login. Password needs to be set as well, and will be used for SASL, not PASS login.
This function can be called to reconnect a closed connection.
Returns the ServerConnection object.
- connected = False¶
- get_nickname()[source]¶
Get the (real) nick name.
This method returns the (real) nickname. The library keeps track of nick changes, so it might not be the nick name that was passed to the connect() method.
- get_server_name()[source]¶
Get the (real) server name.
This method returns the (real) server name, or, more specifically, what the server calls itself.
- remove_global_handler(*args)[source]¶
Remove global handler.
See documentation for IRC.remove_global_handler.
- send_raw(string)[source]¶
Send raw string to the server.
The string will be padded with appropriate CR LF.
- set_keepalive(interval)[source]¶
Set a keepalive to occur every interval on this ServerConnection.
- Parameters:
interval – int in seconds, or datetime.timedelta
- set_rate_limit(frequency)[source]¶
Set a frequency limit (messages per second) for this connection. Any attempts to send faster than this rate will block.
- socket = None¶
- exception irc.client.ServerNotConnectedError[source]¶
Bases:
ServerConnectionError
- class irc.client.SimpleIRCClient[source]¶
Bases:
object
A simple single-server IRC client class.
This is an example of an object-oriented wrapper of the IRC framework. A real IRC client can be made by subclassing this class and adding appropriate methods.
The method on_join will be called when a “join” event is created (which is done when the server sends a JOIN messsage/command), on_privmsg will be called for “privmsg” events, and so on. The handler methods get two arguments: the connection object (same as self.connection) and the event object.
Functionally, any of the event names in events.py may be subscribed to by prefixing them with on_, and creating a function of that name in the child-class of SimpleIRCClient. When the event of event_name is received, the appropriately named method will be called (if it exists) by runtime class introspection.
See _dispatcher(), which takes the event name, postpends it to on_, and then attemps to look up the class member function by name and call it.
Instance attributes that can be used by sub classes:
reactor – The Reactor instance.
connection – The ServerConnection instance.
dcc_connections – A list of DCCConnection instances.
- dcc(*args, **kwargs)[source]¶
Create and associate a new DCCConnection object.
Use the returned object to listen for or connect to a DCC peer.
- dcc_connect(address, port, dcctype='chat')[source]¶
Connect to a DCC peer.
Arguments:
address – IP address of the peer.
port – Port to connect to.
Returns a DCCConnection instance.
- irc.client.ip_numstr_to_quad(num)[source]¶
Convert an IP number as an integer given in ASCII representation to an IP address string.
>>> ip_numstr_to_quad('3232235521') '192.168.0.1' >>> ip_numstr_to_quad(3232235521) '192.168.0.1'
irc.connection module¶
- class irc.connection.AioFactory(**kwargs)[source]¶
Bases:
object
A class for creating async custom socket connections.
To create a simple connection:
server_address = ('localhost', 80) Factory()(protocol_instance, server_address)
To create an SSL connection:
Factory(ssl=True)(protocol_instance, server_address)
To create an IPv6 connection:
Factory(ipv6=True)(protocol_instance, server_address)
Note that Factory doesn’t save the state of the socket itself. The caller must do that, as necessary. As a result, the Factory may be re-used to create new connections with the same settings.
- class irc.connection.Factory(bind_address=None, wrapper=identity, ipv6=False)[source]¶
Bases:
object
A class for creating custom socket connections.
To create a simple connection:
server_address = ('localhost', 80) Factory()(server_address)
To create an SSL connection:
context = ssl.create_default_context() wrapper = functools.partial(context.wrap_socket, server_hostname=server_address) Factory(wrapper=wrapper)(server_address)
To create an SSL connection with parameters to wrap_socket:
context = ssl.create_default_context() wrapper = functools.partial(context.wrap_socket, server_hostname=server_address, ssl_cert=get_cert()) Factory(wrapper=wrapper)(server_address)
To create an IPv6 connection:
Factory(ipv6=True)(server_address)
Note that Factory doesn’t save the state of the socket itself. The caller must do that, as necessary. As a result, the Factory may be re-used to create new connections with the same settings.
- family = 2¶
irc.ctcp module¶
Handle Client-to-Client protocol per the best available spec.
- irc.ctcp.dequote(message)[source]¶
Dequote a message according to CTCP specifications.
The function returns a list where each element can be either a string (normal message) or a tuple of one or two strings (tagged messages). If a tuple has only one element (ie is a singleton), that element is the tag; otherwise the tuple has two elements: the tag and the data.
Arguments:
message – The message to be decoded.
irc.dict module¶
- class irc.dict.IRCDict(*args, **kargs)[source]¶
Bases:
KeyTransformingDict
A dictionary of names whose keys are case-insensitive according to the IRC RFC rules.
>>> d = IRCDict({'[This]': 'that'}, A='foo')
The dict maintains the original case:
>>> '[This]' in ''.join(d.keys()) True
But the keys can be referenced with a different case
>>> d['a'] == 'foo' True
>>> d['{this}'] == 'that' True
>>> d['{THIS}'] == 'that' True
>>> '{thiS]' in d True
This should work for operations like delete and pop as well.
>>> d.pop('A') == 'foo' True >>> del d['{This}'] >>> len(d) 0
irc.events module¶
- class irc.events.Command(code, name)[source]¶
Bases:
str
- static lookup(raw) Command [source]¶
Lookup a command by numeric or by name.
>>> Command.lookup('002') 'yourhost' >>> Command.lookup('002').code '002' >>> int(Command.lookup('002')) 2 >>> int(Command.lookup('yourhost')) 2 >>> Command.lookup('yourhost').code '002'
If a command is supplied that’s an unrecognized name or code, a Command object is still returned. >>> fallback = Command.lookup(‘Unknown-command’) >>> fallback ‘unknown-command’ >>> fallback.code ‘unknown-command’ >>> int(fallback) Traceback (most recent call last): … ValueError: invalid literal for int() with base 10: ‘unknown-command’ >>> fallback = Command.lookup(‘999’) >>> fallback ‘999’ >>> int(fallback) 999
irc.features module¶
- class irc.features.FeatureSet[source]¶
Bases:
object
An implementation of features as loaded from an ISUPPORT server directive.
Each feature is loaded into an attribute of the same name (but lowercased to match Python sensibilities).
>>> f = FeatureSet() >>> f.load(['target', 'PREFIX=(abc)+-/', 'your message sir']) >>> f.prefix == {'+': 'a', '-': 'b', '/': 'c'} True
Order of prefix is relevant, so it is retained.
>>> tuple(f.prefix) ('+', '-', '/')
>>> f.load_feature('CHANMODES=foo,bar,baz') >>> f.chanmodes ['foo', 'bar', 'baz']
irc.modes module¶
- irc.modes.parse_channel_modes(mode_string)[source]¶
Parse a channel mode string.
The function returns a list of lists with three members: sign, mode and argument. The sign is “+” or “-”. The argument is None if mode isn’t one of “b”, “k”, “l”, “v”, “o”, “h”, or “q”.
Example:
>>> parse_channel_modes("+ab-c foo") [['+', 'a', None], ['+', 'b', 'foo'], ['-', 'c', None]]
- irc.modes.parse_nick_modes(mode_string)[source]¶
Parse a nick mode string.
The function returns a list of lists with three members: sign, mode and argument. The sign is “+” or “-”. The argument is always None.
Example:
>>> parse_nick_modes("+ab-c") [['+', 'a', None], ['+', 'b', None], ['-', 'c', None]]
irc.rfc module¶
irc.schedule module¶
- class irc.schedule.DefaultScheduler[source]¶
Bases:
InvokeScheduler
,IScheduler
irc.server module¶
irc.server
This server has basic support for:
Connecting
Channels
Nicknames
Public/private messages
It is MISSING support for notably:
Server linking
Modes (user and channel)
Proper error reporting
Basically everything else
It is mostly useful as a testing tool or perhaps for building something like a private proxy on. Do NOT use it in any kind of production code or anything that will ever be connected to by the public.
- class irc.server.IRCClient(request, client_address, server)[source]¶
Bases:
BaseRequestHandler
IRC client connect and command handling. Client connection is handled by the
handle
method which sets up a two-way communication with the client. It then handles commands sent by the client by dispatching them to thehandle_
methods.- exception Disconnect[source]¶
Bases:
BaseException
- finish()[source]¶
The client conection is finished. Do some cleanup to ensure that the client doesn’t linger around in any channel or the client list, in case the client didn’t properly close the connection with PART and QUIT.
- exception irc.server.IRCError(code, value)[source]¶
Bases:
Exception
Exception thrown by IRC command handlers to notify client of a server/client error.
- class irc.server.IRCServer(*args, **kwargs)[source]¶
Bases:
ThreadingMixIn
,TCPServer
- allow_reuse_address = True¶
- channels: Dict[str, IRCChannel] = {}¶
Existing channels by channel name
- daemon_threads = True¶
irc.strings module¶
- class irc.strings.IRCFoldedCase[source]¶
Bases:
FoldedCase
A version of FoldedCase that honors the IRC specification for lowercased strings (RFC 1459).
>>> IRCFoldedCase('Foo^').lower() 'foo~'
>>> IRCFoldedCase('[this]') == IRCFoldedCase('{THIS}') True
>>> IRCFoldedCase('[This]').casefold() '{this}'
>>> IRCFoldedCase().lower() ''
- casefold()[source]¶
Ensure cached superclass value doesn’t supersede.
>>> ob = IRCFoldedCase('[This]') >>> ob.casefold() '{this}' >>> ob.casefold() '{this}'
- translation = {91: 123, 92: 124, 93: 125, 94: 126}¶