Getting Started

Welcome! This page is designed for someone who has never used KitnIRC before and wants to get a sense of its general layout and features. It is designed to complement the example code provided within the repository.

Overall Structure

KitnIRC has two major components:

• The Client, which handles the IRC protocol communications with the server (and can be used on its own if you just want a wrapper around IRC commands and messages).
• The Controller, which provides a system for building independent modules that can interact with the IRC server.

The IRC Client

The kitnirc.client.Client object represents a single IRC connection.

Creating a connection

To create a working connection, 3 steps are necessary:

1. Instantiate a Client object, passing it the host (and optionally, port - default 6667) of the IRC server.
2. Call the .connect() method of the Client object, passing it the nick you want to use.
3. Eventually, call the .run() method of the Client object, which will block and process communications to and from the IRC server.

.run() will continue blocking until the connection is broken, either by the server, network issues, or calling .disconnect().

Handling incoming events

A given Client has a set of event handlers to which it will dispatch events based on communications with the IRC server - for instance, the WELCOME event is dispatched once the client has joined the IRC server as a valid user. (A list of events can be found in client.py - look for the definition of self.event_handlers).

You can add a new handler for a given event by calling the add_handler method on a Client instance, passing it the name of the event and a function to call when that event is triggered. Event handler functions are called with the Client instance that raised the event as their first argument, followed by zero or more additional arguments depending on which event they are handling. (To look up the exact arguments passed for a given event, see the COMMAND PARSERS section of client.py.)

Sending commands

Client also provides a number of methods for sending commands to the IRC server. The most bare-bones of these is .send(), which simply sends a raw line to the server. It will take any number of arguments and automatically join them together with spaces and add a newline at the end before sending the line to the server. (As a sanity check, it will raise an exception if your arguments contain any newlines.)

Other methods include most of the common actions you'd expect an IRC bot to do - .nick() attempts to change the client's nickname, .msg() sends a message to a channel or user, and so on. You can find the full set in client.py below the definition of the .send() method; all of them have docstrings describing their function.

Entity classes

A Client uses a handful of other classes to encapsulate certain types of data and provide utility functions related to that data. For instance, the kitnirc.user.User instance represents an individual user entity, a kitnirc.client.Channel instance represents a channel, and a kitnirc.client.Host instance represents a server.

Host instances tend to contain one or more Channel instances in their .channels property; Channel instances tend to contain one or more User instances in their .members property.

In almost all cases, you should treat the data stored in these classes as read-only. The values are set automatically by KitnIRC as it keeps track of the state of the connection, and modifying them manually may result in incorrect or duplicate entries.