Class IRC

Table of contents Index

# class IRC - Class that handles one or several IRC server connections.

Declared in module irclib

## Synopsis

    class IRC:
        def __init__(self, fn_to_add_socket=None, fn_to_remove_socket=None, fn_to_add_timeout=None) # Constructor for IRC objects.
        def _handle_event(self, connection, event) # [Internal]
        def _remove_connection(self, connection) # [Internal]
        def add_global_handler(self, event, handler, priority=0) # Adds a global handler function for a specific event type.
        def disconnect_all(self, message='') # Disconnects all connections.
        def execute_at(self, at, function, arguments=()) # Execute a function at a specified time.
        def execute_delayed(self, delay, function, arguments=()) # Execute a function after a specified time.
        def process_data(self, sockets) # Called when there is more data to read on connection sockets.
        def process_forever(self, timeout=0.2) # Run an infinite loop, processing data from connections.
        def process_once(self, timeout=0) # Process data from connections once.
        def process_timeout(self) # Called when a timeout notification is due.
        def remove_global_handler(self, event, handler) # Removes a global handler function.
        def server(self) # Creates and returns a ServerConnection object.

## Description

When an IRC object has been instantiated, it can be used to create Connection objects that represent the IRC connections. The responsibility of the IRC object is to provide an event-driven framework for the connections and to keep the connections alive. It runs a select loop to poll each connection's TCP socket and hands over the sockets with incoming data for processing by the corresponding connection.

The methods of most interest for an IRC client writer are server, add_global_handler, remove_global_handler, execute_at, execute_delayed, process_once and process_forever.

### Here is an example:

        irc = irclib.IRC()
        server = irc.server()
        server.connect("irc.some.where", 6667, "my_nickname")
        server.privmsg("a_nickname", "Hi there!")
        server.process_forever()

This will connect to the IRC server irc.some.where on port 6667 using the nickname my_nickname and send the message "Hi there!" to the nickname a_nickname.

## __init__(self, fn_to_add_socket=None, fn_to_remove_socket=None, fn_to_add_timeout=None)

Constructor for IRC objects.

Optional arguments are fn_to_add_socket, fn_to_remove_socket and fn_to_add_timeout. The first two specify functions that will be called with a socket object as argument when the IRC object wants to be notified (or stop being notified) of data coming on a new socket. When new data arrives, the method process_data should be called. Similarly, fn_to_add_timeout is called with a number of seconds (a floating point number) as first argument when the IRC object wants to receive a notification (by calling the process_timeout method). So, if e.g. the argument is 42.17, the object wants the process_timeout method to be called after 42 seconds and 170 milliseconds.

The three arguments mainly exist to be able to use an external main loop (for example Tkinter's or PyGTK's main app loop) instead of calling the process_forever method.

An alternative is to just call ServerConnection.process_once() once in a while.

## add_global_handler(self, event, handler, priority=0)

Adds a global handler function for a specific event type.

event
  Event type (a string). Check the values of the numeric_events dictionary in irclib.py for possible event types.
handler
  Callback function.
priority=0
  A number (the lower number, the higher priority).

The handler function is called whenever the specified event is triggered in any of the connections. See documentation for the Event class.

The handler functions are called in priority order (lowest number is highest priority). If a handler function returns "NO MORE", no more handlers will be called.

## process_data(self, sockets)

Called when there is more data to read on connection sockets.

sockets
  A list of socket objects.

See documentation for IRC.__init__.

## process_forever(self, timeout=0.2)

Run an infinite loop, processing data from connections.

timeout=0.2
  Parameter to pass to process_once.

This method repeatedly calls process_once.

## process_once(self, timeout=0)

Process data from connections once.

timeout=0
  How long the select() call should wait if no data is available.

This method should be called periodically to check and process incoming data, if there are any. If that seems boring, look at the process_forever method.

## process_timeout(self)

Called when a timeout notification is due.

See documentation for IRC.__init__.

## remove_global_handler(self, event, handler)

Removes a global handler function.

event
  Event type (a string).
handler
  Callback function.

Returns 1 on success, otherwise 0.