JustIRC is a Python IRC library that can be used to create IRC bots and clients. It is an event-based library, you can read more about which events are available from the Events page.

The library recently had a major version update, which changed the API. If you don’t want to migrate your code to the new API, please use version 0.3.

Quick Start¶

Before going into detail on how the library works, here’s a quick example to see how to use it:

import JustIRC

bot = JustIRC.IRCConnection()

@bot.on("connect")
def connect(e):
  bot.set_nick("TestBot")
  bot.send_user_packet("TestBot")

@bot.on("welcome")
def welcome(e):
  bot.join_channel("#HelloBotTest")

@bot.on("message")
def message(e):
  message = e.message.lower()
  if "hello" in message:
    message = f"Hello, {e.sender}"
    bot.send_message(e.channel, message)

bot.connect("irc.freenode.net")
bot.run_loop()

Event Emitter¶

JustIRC contains a simple Event Emitter. It provides a mechanism to listen and emit arbitrary events. This is useful for building clients that react to incoming messages, such as bots.

The design of the event system is similar to those found in web browsers or JS runtimes, so it should be familiar to JS developers.

Emitting events¶

In order to emit events, you can call the _emit_ method on an EventEmitter instance. Here’s an example:

emitter.emit("lucky-number", random.randint(1, 100))

For real-life use cases, the event data will probably be an object with multiple properties instead of a single number.

The library uses this mechanism to emit events for IRC messages, but your bot can emit custom events for its own behaviour.

If there are no listeners for an event, it doesn’t consume resources.

Handling events with decorators¶

The easiest way to handle an event is by putting a decorator on a handler function. Let’s make a handler for the lucky-number event above.

@emitter.on("lucky-number")
def number_handler(num):
  print("Your lucky number is", num)

Events¶

JustIRC emits certain events regularly. Below is a list of them. Some other events are emitted too, but they are not listed below since they are not guaranteed to be kept around.

‘connected’¶

This event is emitted when the client connects to the server.

‘welcome’¶

After the client connects to the server and receives the welcome message, the ‘welcome’ event is emitted.

‘message’¶

This event is emitted when a message is received. It does not discriminate between private messages and channel messages.

The event data includes

sender (str): The nickname of the sender.
channel (str): The channel that the message was sent to
message (str): The message contents

‘message#’¶

This event is only emitted for messages sent to a channel. The event data is the same as the message event.

‘pm’¶

This is emitted for private messages. The event data is the same as the message event.

‘ping’¶

Every time the client receives a PING from the server, a ping event is emitted. There is no need to handle this explicitly, as the library replies to pings automatically.

‘packet’¶

On every received packet, a ‘packet’ event is emitted. This is generally not very useful to simple bots. It can be used for debugging, or for implementing functionality that’s not part of JustIRC.

The event data includes

packet: The received packet
- prefix: Message prefix
- command: Message command
- arguments: Message arguments

Full API¶

class JustIRC.EventEmitter¶

emit(name, data=None)¶

Emit an event

This function emits an event to all listeners registered to it.

Parameters:	name (str) – Event name. Case sensitive. data – Event data. Can be any type and passed directly to the event handlers.

on(name)¶

Decorate a function as an event handler.

Parameters:	name (str) – The event name to handle

class JustIRC.IRCConnection¶

connect(server, port=6667, tls=False)¶

Connects to the IRC server

Parameters:	server (str) – The server IP or domain to connect to port (int) – The server port to connect to tls (bool) – Enable the use of TLS

join_channel(channel)¶

Join a channel

This function joins a given channel. After the channel is joined, the “join” event is emitted with your nick.

Parameters:	channel (str) – The channel to join

run_loop()¶

Runs the main loop of the client

This function is usually called after you add all the callbacks and connect to the server. It will block until the connection to the server is broken.

run_once()¶

Run one iteration of the IRC client.

This function is called in a loop by the run_loop function. It can be called separately, but most of the time there is no need to do this.

send_action_message(to, action)¶

Send an action message to a channel or user.

Action messages can have special formatting on clients and are usually send like /me is happy

Parameters:	to (str) – The target of the message. Can be a channel or a user. action (str) – The message content

send_line(line)¶

Sends a line directly to the server.

This is a low-level function that can be used to implement functionality that’s not covered by this library. Almost all of the time, you should have no need to use this function.

Parameters:	line (str) – The line to send to the server

send_message(to, message)¶

Sends a message to a user or a channel

This is the main method of interaction as an IRC bot or client. This function results in a PRIVMSG packet to the server.

Parameters:	to (str) – The target of the message message (str) – The message content

send_notice(to, message)¶

Send a notice message

Notice messages usually have special formatting on clients.

Parameters:	to (str) – The target of the message message (str) – The message content

send_user_packet(username)¶

Send a user packet

This should be sent after your nickname. It is displayed on the clients when they view your details and look at “Real Name”.

Parameters:	username (str) – The name to set

set_nick(nick)¶

Sets or changes your nick

This should be called before joining channels, but can be called at any time afterwards. If the requested nick is not available, the library will keep adding underscores until an available nick is found.

Parameters:	nick (str) – The nickname to use