Extension:XMLRC/rcclient.py

  is a client library for handling XMLRC events received via XMPP, provided as part of the XMLRC extension. It is located in the  directory of XMLRC. You can place this directory anywhere on your system. In fact, for security reasons, it is recommended to move it to a location that is not accessible from the web or by the web server.

rcclient.py is a standalone python library but it may also be run as a program. It will then dump all the recentchanges items it receives to the console. This is useful mainly for testing and debugging. Note that some configuration is needed for rcclient.py to work as a standalone program.

Using rcclient as a library
rcclient.py provides functionality for listening for XMPP messages, optionally in a MUC room, and extract any RC items from them, and passing them to a handler. A program that wishes to react to changes on a wiki can thus simply start an RCClient and register a handler function that will be called whenever a change item is received.

class RCClient
This class implements a client that listens for XMPP messages, analyses them, and hands them to any registered handlers. Core methods are:


 * __init( self, console_encoding = 'utf-8' )__: creates the RCClient. You can set console_encoding to match your local encoding.
 * add_handler( self, handler ): Add a handler. The handler must either be callable (e.g. a function), or an instance implementing the method process(self, rc). The handler will be called with a single paramer, which is an instance of RecentChange (see below).
 * connect( self, jid, password ): Connects the client to a jabber server, using the given credentials
 * join( self, room, nick = None ): Makes the client join the specifid MUC room. The room is specified as a JID. If no nick is given, The client will join the room with the name taken from the node part of the JID it connected with.
 * service_loop( self ): This is the main entry point. Run this to listen for messages, and react to them.

Example:

class RCHandler
This is the base class for handlers that can be registered with. Subclasses must implement the method, which will be called whenever a message containing RC data is received. The rc argument will be an instance of RecentChange.

Alternatively to an ionstance of RCHandler, a function (or other callable) taking a single argument can also be registered with.

class RecentChange
The class RecentChange is a wrapper around the  tag extracted from an XMPP message. It provides covenient access to all properties of the change item, using item syntax (e.g. rc["revid"]) or attribute syntax (e.g. rc.revid). Well known attributes are converted to the appropriate type automatically.

Nested tags are available by they tag name, support for these is however still limited.

Installation
rcclient.py is a standalone library, you can place it anywhere in your system. It requires xmpppy library from  and python 2.5 or later. Make sure python can find both rcclient and xmpppy, e.g. by adjusting your PYTHONPATH environment variable.

If you want to run rcclient.py as a program, you need to set up the configuration file rcclient.ini. You can do so by renaming rcclient.ini.sample to rcclient.ini, then put the credentials for the Jabber acount into the config file. Note: make sure the file is not accessible from the web!

Configuration
The configuration file rcclient.ini contains a single section:


 * [XMPP] specifies the XMPP credentials for connectiong to the jabber server.
 * jid: the Jabber ID (JID) to use for login / identification
 * password: passoword for logging into the Jabbber server. Note: make sure this file isn't readable from the web!

This configuration is only needed to run rcclient.py as a program. When using it as a library, you are free to provide the credentials from wherever you like.

Running rcclient.py
rcclient.py can run as a program, for testing and demostration purposes. It simply echos all RC information it receives to the console.

When everything is configured, you can start rcclient.py simply by typing:

python rcclient.py

If you want to join a chat room (that is, if udp2xmpp.py sends the messages to a chat room), you have to specify the romm's JID:

python rcclient.py recentchanges@conference.jabber.example.com

In addition, rcclient supports the following command line arguments:


 * --config: the configuration file to use. If not given, rcclient.ini will be looked for in the directory where rcclient.py resides.
 * --quiet: set verbosity to quiet. Only warnings and errors are reported
 * --debug: set verbosity to debug (noisy)
 * --nick: the nickname to use when joining the chat room. If not given, the node name from the jid used for login will be used.
 * --xml: output raw  tags instead of interpreted RC data, for testing/debugging
 * --stanzas: output full XMPP stanzas instead of RC data, for testing/debugging.