A lightweight IRC framework.
A simple IRC client framework.
To install miniirc, simply run
pip3 install miniirc as root.
irc = miniirc.IRC(ip, port, nick, channels = None, *, ssl = None, ident = None, realname = None, persist = True, debug = False, ns_identity = None, auto_connect = True, ircv3_caps = set(), quit_message = 'I grew sick and died.', ping_interval = 60, verify_ssl = True)
||The IP/hostname of the IRC server to connect to.|
||The port to connect to.|
||The nickname of the bot.|
||The channels to join on connect.|
||Enable TLS/SSL. If
||The ident to use, defaults to
||The realname to use, defaults to
||Whether to automatically reconnect.|
||Enables debug mode, prints all IRC messages. This can also be a file-like object (with write mode enabled) if you want debug messages to be written into a file instead of being printed to stdout, or a function (for example
||The NickServ account to use (
||A set() of additional IRCv3 capabilities to request. SASL is auto-added if
||A mode string (for example
||Sets the default quit message. This can be modified per-quit with
||If no packets are sent or received for this amount of seconds, miniirc will send a
||Verifies TLS/SSL certificates. Disabling this is not recommended. If you have trouble with certificate verification, try running
||See the message parser section for documentation.|
||Connects to the IRC server if not already connected.|
||Disconnects from the IRC server.
||An event handler, see Handlers for more info.|
||Sends a raw message to IRC, use
These variables should not be changed outside
||New in 1.1.0. A
||New in 1.1.0. The maximum length (in bytes) of messages (including
||The current nickname.|
@-rules called in their own thread when their respective IRC event(s) is/are received. Handlers may be global (
@miniirc.handler) or local (
@miniirc.IRC().handler) to a certain IRC connection. New handlers are added to existing IRC connections automatically since miniirc 0.3.2.
The basic syntax for a handler is as followed, where
*events is a list of events (
NOTICE, etc) are called.
import miniirc @miniirc.Handler(*events) def handler(irc, hostmask, args): # irc: An 'IRC' object. # hostmask: A 'hostmask' object. # args: A list containing the arguments sent to the command. # Everything following the first `:` in the command # is put into one item (args[-1]). pass
Hostmasks are tuples with the format
('user', 'ident', 'hostname'). If
hostname aren't sent from the server, they will be filled in with the previous value. If a command is received without a hostmask, all the
hostmask parameters will be set to the name of the command.
Making existing functions handlers
You can make existing functions handlers (for example class instance methods)
irc.Handler(*events)(handler_function). You probably don't want to use
miniirc.Handler for class instance methods, as this will create a handler
that gets triggered for every
You can also add multiple handlers of the same type easily:
add_handler = irc.Handler('PRIVMSG') add_handler(handler_1) add_handler(self.instance_handler)
This is useful if you want to create a
Client) class and add
class-specific handlers without creating global process-wide handlers or
creating a wrapper function for every class instance.
If you want your handler to support IRCv3 message tags, you need to add
ircv3 = True to the
Handler at-rule. You will need to add a
to your function after
hostmask. IRCv3 tags are sent to the handlers as
dicts, with values of either strings or
Since version 0.3.8, miniirc will automatically un-escape IRCv3 tag values.
import miniirc @miniirc.Handler(*events, ircv3 = True) def handler(irc, hostmask, tags, args): pass
You can handle IRCv3 capabilities before connecting using a handler.
You must use
force = True on any
irc.quote() called here, as when this is
called, miniirc has not yet connected.
import miniirc @miniirc.Handler('IRCv3 my-cap-name') def handler(irc, hostmask, args): # Process the capability here # IRCv3.2 capabilities: # args = ['my-cap-name', 'IRCv3.2-parameters'] # IRCv3.1 capabilities: # args = ['my-cap-name'] # Remove the capability from the processing list. irc.finish_negotiation(args) # This can also be 'my-cap-name'.
Custom message parsers
If the IRC server you are connecting to supports a non-standard message syntax, you can
create custom message parsers. These are called with the raw message (as a
can either return
None to ignore the message or a 4-tuple (
cmd, hostmask, tags, args)
that will then be sent on to the handlers. The items in this 4-tuple should be the same
type as the items expected by handlers (and
cmd should be a string).
Message parser example
This message parser makes the normal parser allow
~ as an IRCv3 tag prefix character.
import miniirc def my_message_parser(msg): if msg.startswith('~'): msg = '@' + msg[1:] return miniirc.ircv3_message_parser(msg)
Changing message parsers
To change message parsers, you can use
irc.change_parser(func = ...). If
func is not
specified, it will default to the built-in parser. You can only change message parsers
on-the-fly (for example in an IRCv3 CAP handler). If you need to change message parsers
before connecting, you can disable
auto_connect and change it then.
irc = miniirc.IRC(..., auto_connect = False) irc.change_parser(my_message_parser) irc.connect()
Handling multiple events
New in version 1.3.0.
If you want to handle multiple events and/or be able to get the name of the
event being triggered, you can use
irc.CmdHandler. This will pass an extra
command argument to the handler function (between
containing a string with the command name (such as
Please do not use these unless there is no other alternative.
If you want to handle every event, you can use catch-all handlers. To create
these, you can call
irc.CmdHandler() without any parameters. Note that this
handler will be called many times while connecting (and once connected).
You cannot call
irc.Handler() without parameters.
import miniirc @miniirc.Handler('PRIVMSG', 'NOTICE') def handler(irc, hostmask, args): print(hostmask, 'sent a message to', args, 'with content', args) # nickname sent a message to #channel with content :Hello, world! @miniirc.CmdHandler('PRIVMSG', 'NOTICE') def cmdhandler(irc, command, hostmask, args): print(hostmask, 'sent a', command, 'to', args, 'with content', args) # nickname sent a PRIVMSG to #channel with content :Hello, world!
This will print a line whenever the bot gets a
miniirc provides the following helper functions:
||The default IRCv2/IRCv3 message parser, returns
||A tuple containing version information.|
The version numbering system should be similar to SemVer, however backwards compatibility is preserved where possible when major releases change. Patch version numbers can and will increase quickly, as miniirc is (at the time of writing this) under active development.
Python version support
- Python 2 does not work and will (probably) never work with miniirc. If you MUST use Python 2, you can use the (probably outdated and bug-filled) python2 branch.
- Python 3.3 and below probably won't work, and fixes will not be added unless they are very trivial.
- Python 3.4 is not tested as thoroughly, however should work (and does with version 1.2.3).
- Python 3.5 and above should work with the latest stable version of miniirc.
Here is a list of some (open-source) bots using miniirc, in alphabetial order:
- irc-rss-feed-bot - Posts RSS entry titles and shortened URLs to IRC channels. Python 3.7+
- irc-url-title-bot - Gets webpage titles from URLs posted in IRC channels. Python 3.7+
- lurklite - A generic configurable IRC bot. GitHub link.
- stdinbot - A very simple bot that dumps stdin to an IRC channel. GitHub link.
Release history Release notifications
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size & hash SHA256 hash help||File type||Python version||Upload date|
|miniirc-1.3.3-py3-none-any.whl (12.5 kB) Copy SHA256 hash SHA256||Wheel||py3|
|miniirc-1.3.3.tar.gz (15.5 kB) Copy SHA256 hash SHA256||Source||None|