Extension:XMLRC/rcclient.py

From MediaWiki.org
Jump to: navigation, search

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 client 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[edit | edit source]

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[edit | edit source]

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:

    # create rc client instance
    client = RCClient( )
 
    # register handler
    client.add_handler( my_rc_handler ) 
 
    # connect
    client.connect( jid, password )
 
    # join chat room
    # the client will then receive all messages posted to that room
    # otherwise, it will only receive messages directly addressed to its own jid
    client.join( room )
 
    # run listener loop
    # whenever a message is received that contains RC data, my_rc_handler is called
    client.service_loop( )

class RCHandler[edit | edit source]

This is the base class for handlers that can be registered with RCClient.add_handler(). Subclasses must implement the method process(self, rc), 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 RCClient.add_handler().

class RecentChange[edit | edit source]

The class RecentChange is a wrapper around the <rc> 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[edit | edit source]

rcclient.py is a standalone library, you can place it anywhere in your system. It requires xmpppy library from <http://xmpppy.sourceforge.net/> 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[edit | edit source]

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[edit | edit source]

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 <rc> tags instead of interpreted RC data, for testing/debugging
--stanzas
output full XMPP stanzas instead of RC data, for testing/debugging.