Next
Previous
Contents
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.
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:
- File, the main menu
- Connect... pops up the connect dialog
which appears on startup
- Disconnect closes the server
connection
- Quit quits PyIRC, after confirmation
- Options is the options menu, common to all
windows
- Colors... pops up a dialog box
designed for the customization of the colors of the text
in
version 0.07, this feature is not yet available
- Fonts... pops up a dialog box for the
selection of the font common to the message widget and to the command line
- Bookmarks is the bookmarks menu
- Channels is the submenu for the channel
bookmarks. It pops up a submenu which contains a first entry with the
Add bookmark option, and with one entry per bookmark. If you
click on Add bookmark, you will be prompted for a new
bookmark. If you click on one of the bookmarks, you will join the
channel selected.
- Queries is the same submenu, but for
queries. A query is a private conversation with someone.
- Save bookmarks permits you to save the
bookmarks you have added for a future PyIRC session. It will write the
bookmarks in the file
$HOME/.pyirc.bookmarks
, where
$HOME
is your home directory
- Help is for the help menu, which does not
need explainations.
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:
- Bold is produced when the text is
surrounded by
CTRL-B
(ASCII 2) characters.
- Reverse is produced when the text is
surrounded by
CTRL-V
(ASCII 22) characters.
- Underline is produced when the text is
surrounded by
CTRL-_
(ASCII 31) characters.
- A beep is produced when the text printed
contains a
CTRL-G
(ASCII 7) character.
- In a future version, the support for mIRC's
colors will be added.
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.
PyIRC provides basic commands that can be used on the
command line:
- admin [<server>|<nickname>]:
displays the administrative details about the given server. If no
server is specified, the server you are connected to is used. If a
nickname is supplied then it gives the administrative information for
that person's current server.
- away [<away message>]: marks you as
"away". Whenever someone sends you a message or does a whois on
you, they will automatically see whatever message you set. Using
away with no parameters marks you as no longer being away.
- beep: makes the client beep.
- cd [<path>]: if a <path> is
specified, this changes PyIRC's working directory. cd with no
arguments shows you the current directory.
- clear [<window>]: clears the window named
<window>. If no parameters is used, it clears the window where the
command was entered. See the section about window names to get
information on window names.
- close [<window>]: closes the window named
<window>. If no parameters is given, it closes the window where
the command was entered.
- ctcp <nick> <command>
[<args>]: sends a ctcp <command> to
<nick> with optional <args>.
- ctcp_reply <nick> <command>
[<args>]: sends a ctcp reply <command> to
<nick> with optional <args>.
- info [<server>]: shows info
about <server>, or your server if no parameters.
- invite <nickname>
[<channel>]: invites another user to a channel. If no
channel is specified, the channel from which you entered the command
is used.
- join <channel> [<key>]:
makes you join the channel <channel>. Channel names begin with a
# or & and may contain any character except space, carriage
return, null and line feed. Channel names beginning with & are
local to your server. The channel will be created if the specified
channel does not already exist. Otherwise, if
MODE +k <key>
is enabled on the channel, you wil have to supply the <key> to
complete join.
- kick [<channel>] <nick>
[<comment>]: kicks <nick> from <channel>
using <comment> for reason. If <channel> is not supplied,
it will be set to the channel from which you entered the command. You
must have channel operator priviledges to use this command.
- kill <nickname> <comment>: removes
<nickname> from IRC. You need to have IRC operator priviledges
to use this command, with extreme caution.
- leave [<channel>]: leave a
channel you are on. If no channel is specified, it will leave the
channel from which you issued the command.
- links [<wildcard>]: shows all
of the servers currently connected to your IRC network. If
<wildcard> is specified, it shows any server matching the given
wildcard.
- list [<channel>]: lists the
channel <channel> or all the channels if <channel> is not
supplied.
- load <file>: loads <file> into
IRC. This is the only way to load and execute scripts. See the section
about scripts in this document for further details.
- me <action description>: sends a
description of what you are doing or how you are feeling or anything
else to the current window.
- mode
- motd
[<server>|<nickname>]: gives the
message-of-the-day of <server> or of <nickname>'s
server. If no parameter is given, it prints your server's MOTD.
- msg <nickname>|<channel>
<text>: sends a private message to <nickname> or sends a
message to the channel <channel>. Note that you only can a
message to <channel> if it exists and its mode is not +n or if
your on the channel.
- nick <nickname>: changes your nickname to
<nickname>. Valid nicknames are up to 9 characters long. If
<nickname> is bigger, it will be truncated.
- notice <nickname>|<channel>
<text>: sends a private message to <nickname> or to
lt;channel>. Unlike msg, no automated response messages will
be sent in response to a notice. It's the only difference with
msg.
- on: see the chapter about this command.
- oper [<nickname>
[<password>]]: gives you IRC operator
priviledges if the correct nickname and password are given. If
password is not given, you will be prompted for one. If no nickname is
given, your current nickname will be used.
- ping <nickname>: sends a CTCP PING
<current time> to <nickname>. It's a good way to measure
the lag.
- query <nickname>: pops up a message
window, to start a private conversation with <nickname>. It does
not verify that <nickname> exist.
- quit [<reason>]: disconnects
from the server. It does not close your PyIRC session. To finish your
PyIRC session, you have to use close in the server window.
- quote <server command>: sends <server
command> directly to the server. No parsing or verification is done
by the client.
- say <text>: sends <text> as if you
had typed it in the window.
- stats c|h|k|i|l|m|o|u|y
[<server>]: shows some irc server usage
statistics.
- c - Shows C and N lines for a given
server. These are the names of the servers that are allowed to
connect.
- h - Shows H and L lines for a given server
(Hubs and Leaves).
- k - Shows K lines for a server. This shows
who is not allowed to connect and possibly at what time they are not
allowed to connect.
- i - Shows I lines. This is who CAN connect
to a server.
- l - Shows information about amount of
information passed to servers and users.
- m - Shows a count for the number of timers
the various commands have been used since the server was booted.
- o - Shows the list of authorized operators
on the server.
- u - Shows the uptime of the server.
- y - Show Y lines, which lists the various
connection classes for a given server.
- topic [<channel>]
[<topic for channel>]: changes the topic for the
named channel. You have to be on the channel to change the topic, and
if the channel mode is +t, then only a channel operator can change the
topic.
- version [<server>]: shows the
version number of the server specified. If no server is specified, the
version of your current server is shown.
- whois [<server>]
<nickname>: shows more detailed information about the nickname
specified. If you specify the server, the answer will come from it. If
you query <nickname>'s server, you will receive extra info about
his idle time.
- whowas <nickname>
[<count>]: shows information about who used the given
nickname last, even if nobody is currently using it. if <count>
is specified, then only the last <count> entries are
shown.
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.
- echo(message, window="-"): prints
<message> in the window named <window>. If <window>
is omitted, prints the message in the server window.
- openwindow(window="-"): ensures that
<window> is showed, or opens it if it does not exist.
- closewindow(window): closes <window>.
- existwindow(window): returns 1 is
<window> exists, 0 otherwise.
- hasnick(channel, nick): returns 1 if you are on
<channel> and <nick> is on <channel> too, 0 otherwise.
- ischanop(channel, nick): returns 1 if you are
on <channel> and <nick> is channel operator on
<channel>
- getstring(title, text, password = 0): pops up a
dialog with title <title>, a <text> and a line editor. If
<password> is 1, the line editor will not show what is typed.
- nickname(): returns your current nickname.
- window(): returns the window from which the
last command was issued.
- encode(text): converts <text> to an
encoded string.
- decode(text): decodes a <text> produced
by encode().
- stime(time): returns a string representing the
time in English, that correspond to <time> seconds since the
epoch.
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:
- A channel window has the name of the channel it
represents. For example
#Unix
or &channel
are valid
channel names, and thus they are valid channel window names.
- A query window has the name of the person you are
talking to.
- And, finally, the name of the server window is "-"
(without the quotes, of course), because this is neither a valid
nickname, nor a valid channel name.
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.
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:
- ACTION - Activated when you receive an
ACTION from someone. The parameters are:
- p0 - Nickname of the person who sent the
ACTION.
- p1 - To whom (nickname or channel) the
ACTION was sent.
- p2 - The message.
- CTCP - To be continued...
- CTCP_REPLY
- JOIN
- KICK
- KILL
- LEAVE
- MODE
- MSG
- MSG_GROUP
- NICKNAME
- NOTICE
- PUBLIC
- PUBLIC_MSG
- PUBLIC_NOTICE
- SEND_ACTION
- SEND_MSG
- SEND_PUBLIC
- SERVER_NOTICE
- SIGNOFF
- TOPIC
- WINDOW_KILL
Next
Previous
Contents