Next Previous Contents

3. Running PyIRC

This section will first explain how to run PyIRC, and what is its default interface. We will then see how to customize PyIRC to your needs.

3.1 Basics

Starting

When you start PyIRC, you will be asked to select a server from the server selection window. As it is the first time you connect, you will have to enter some default values.

First, enter new servers in the server section of the dialog box. Enter the server address in the Server address line editor, and the server port in the Server port line editor. Click on the Add server button to add the server in the server list. You can repeat this operation as many times as you want. Do not remember to select a server in the list, and select the nickname section of the dialog box.

In the nickname section, enter the nickname you want to use in the Nickname line editor. Enter the username we will try to use in the Username line editor. I said we will try, because if the server uses ident and your host has an ident daemon, your username will be your login. Finally, enter your ircname (also known as realname) in the Ircname/Realname line editor, and select the settings section of the dialog box.

In the settings section of the connection dialog box, you can save your current settings (to do so, click on the Save button) or you can revert your changes by clicking on the Load button. The changes are saved in the file $HOME/.pyirc.conf, where $HOME is the user's home directory). You can finally click on the Ok button.

You will be connected to the server you have selected, and the client will register you on the server.

As soon as you get registered (when you receive the "Welcome to the Internet Relay..." message), PyIRC will search a file named $HOME/.pyircrc (where $HOME is the user's home directory) and will execute it, if it is found. This file must be a PyIRC script, as described in a next section.

Server window

The main window is the Server window. This is where all the server-related messages are echoed. The server window is divided into three parts. The top part of the window contains a menu bar, the bottom part of the window, a command line, and in the rest, the message widget, used to display the messages.

The menu bar

Here is a description of the server window's menu bar:

The message widget

The message widget is used to display all the informations. Its behaviour is common to all windows in PyIRC. It displays text with optional attributes:

In all cases, it is better to select a non proportionnal font for the message widget. The default one is Courier 12.

The command line

The command line is common to all windows in PyIRC. However, in the server window, all input must start with the command character, which is / (slash). It allows you to enter commands.

The channel window

A channel window is a window which contains the dialogs of a channel. It allows the user to log the conversations in a file, and it has a nick list, representing the people who are on the channel. You can use the right mouse button to pop up a context sensitive menu

which doesn't work yet in version 0.07
.

The message window

The message window is designed to handle queries with users.

3.2 Basic commands

PyIRC provides basic commands that can be used on the command line:

3.3 Functions for scripts

A special Python module, called pyirc provides various useful functions for writing scripts. Here is the description of these functions, which are part of the pyirc module.

3.4 Writing scripts and aliases

One of the main features of PyIRC is that it allows you to write your own commands and to modify its behaviour, in the Python language. To do so, you have to know how the windows are named in PyIRC, and how the commands are parsed by the client.

Windows' names

Each window in PyIRC has a name, distinct from other window's. This is really simple:

Calls to functions

All the functions called from the command line will have string parameters. There is no error checking, you have to check the parameters yourself. The parameters on the command line are separated by space or tab characters. If the user forgets one parameter, it will be replaced by an empty string. So, if the user types:

/leave
the program will call:
leave('')
as the function expects one parameter.

Imagine that you have an user function called test(), which takes tree parameters.

/test 1                will give          test('1','','')
/test 1 2                "   "            test('1','2','')
/test 1 2 3              "   "            test('1','2','3')
/test 1 2 3 4            "   "            test('1','2','3 4')
/test 1 2 3 4 5          "   "            test('1','2','3 4 5')
etc.

Writing your own aliases

As you can see in the previous section, you have to verify the parameters to your function, especially if it is to be called from the command line. This is the only restriction to aliases.

Suppose that you think that /join is too long, that you are really lazy, and you only want to type /j each time. Then you can use the power of Python to create a simple alias. Just put this text in your .pyircrc file, or anywhere else:

j=join
Then, j will be a perfect alias for join.

Now, you think that you are tired to type the # before each channel name. You can redefine the j alias to be like this one

this is a simple Python function definition
:
def j(channel, key=""):
  # We check the args, and if 'channel' is not valid, add a # before it.
  if channel!='' and channel[0]!='#' and channel[0]!='&':
    join('#'+channel, key)
  else:
    join(channel, key)

Now, what can you do if your aliases are a mess, and you want to call the standard function? All you have to do is to call the function from the pyirc module. For example, let us rewrite the preceding example in another way:

def join(channel, key=""):
  # We check the args, and if 'channel' is not valid, add a # before it.
  if channel!='' and channel[0]!='#' and channel[0]!='&':
    pyirc.join('#'+channel, key)
  else:
    pyirc.join(channel, key)

j=join
By calling pyirc.join instead of join, you are sure that you will get the expected result.

3.5 Customizing events reponses

Like ircII, PyIRC gives you the possiblity to react to different events, by using an /on mechanism.

The on command lets you set actions which will occur when certain events happen. For example, you can create "personalized" away messages for different individuals, periodic actions that occur at specific times, just to name a few.

When used in a window, /on will show you what event handler is installed. It will show you all the event handlers for all the events. If you use the semantic /on <event>, it will show you the actions installed for the particuliar <event>.

You can also install event handlers using the command line, but I recommend the use of scripts, like the .pyircrc file or anything else if you want to control exactly what you want to do.

The actions can get informations from the event by the p0, p1, p2, ... variables.

There are a limited number of events generated by PyIRC. Here is the list:


Next Previous Contents