Keyword assistant

The first main section of the messageCB handler deals with the incoming commands:

    # deal with interaction
    if type == 'chat' or type == 'normal':
        jid = str(msg.getFrom())

        message = split(msg.getBody(), None, 1);
        reply = ""

        if message[0] == 'watch':
            addword(jid, message[1])
            reply = "ok, watching for " + message[1]
        
        if message[0] == 'ignore':
            delword(jid, message[1])
            reply = "ok, now ignoring " + message[1]

        if message[0] == 'list':
            if keywords.has_key(jid):
                reply = "watching for: " + join(keywords[jid].keys(), ", ")
            else:
                reply = "not watching for any keywords"

        if message[0] == 'stop':
            if keywords.has_key(jid):
                del keywords[jid]
                reply = "ok, I've stopped watching"
           
        if reply:
            con.send(msg.build_reply(reply))

Here's that section one chunk at a time.

If the <message/> element turns out to be of the type in which we're expecting a potential command, we want to determine the JID of the correspondent who sent that message. Calling the getFrom() method will return us a JID object. What we need is the string representation of that, which can be determined by calling the str() function on that JID object:

        jid = str(msg.getFrom())

Then we grab the content of the message by calling the getBody() on the msg object, and split the whole thing on the first bit of whitespace. This should be enough for us to distinguish a command ("watch", "ignore", and so on) from the keywords. After the split, the first element (index 0) in the message array will be the command, and the second element (index 1) will be the word or phrase, if given. At this stage we also declare an empty reply.

        message = split(msg.getBody(), None, 1);
        reply = ""

Now it's time to determine whether what the script was sent made sense as a command:

        if message[0] == 'watch':
            addword(jid, message[1])
            reply = "ok, watching for " + message[1]
        
        if message[0] == 'ignore':
            delword(jid, message[1])
            reply = "ok, now ignoring " + message[1]

        if message[0] == 'list':
            if keywords.has_key(jid):
                reply = "watching for: " + join(keywords[jid].keys(), ", ")
            else:
                reply = "not watching for any keywords"

        if message[0] == 'stop':
            if keywords.has_key(jid):
                del keywords[jid]
                reply = "ok, I've stopped watching"

We go through a series of checks, taking appropriate action for our supported commands:

• watch (watch for a particular word or phrase)

• ignore (stop watching for a particular word or phrase)

• list (list the words and phrases currently being watched)

• stop (stop watching altogether—remove my list of words and phrases)

The addword() and delword() functions defined earlier are used here, as well as other simpler functions that list:

keywords[jid].keys()

or remove:

del keywords[jid]

the words and phrases for a particular JID.

If there was something recognisable for the script to do, we get it to reply appropriately:

        if reply:
            con.send(msg.build_reply(reply))

The build_reply() function creates a reply out of a message object by setting the to to the value of the original <message/> element's from attribute, and preserving the element type attribute and <thread/> tag, if present. The <body/> of the reply object (which is, after all, just a <message/> element), is set to whatever is passed in the function call; in this case, it's the text in the reply variable.

Now that we've dealt with incoming commands, we just need another section in the message callback subroutine to scan for the words and phrases. The target texts for this scanning will be the snippets of room conversation, which arrive at the callback in the form of "groupchat" type <message/> elements.

    # scan room talk
    if type == 'groupchat':
        message = msg.getBody()

The message variable holds the string we need to scan, and it's just a case of checking for each of the words or phrases on behalf of each of the users that have asked:

        for jid in keywords.keys():
            for word in keywords[jid].keys():
                if find(message, word) >= 0:
                    con.send(Jabber.Message(jid, word + ": " + message))

If we get a hit, we construct a new Message object, passing the JID of the person for whom the string has matched (in the jid variable), and the notification consisting of the word or phrase that was found (in word) and the context in which it was found (the sentence uttered, in message). The <message/> so constructed, is then sent to that user. By default, the Message constructor specifies no type attribute, so that the user is sent a "normal" message.

We want to check for the possibility of nickname conflict problems which may occur when we enter the room, and our chosen nickname is already taken.

Remembering that a conflict notification will look something like this:

<presence to='qmacro@jabber.com/jarltk'
        from='cellar@conf.merlix.dyndns.org/flash' 
        type='error'>
  <error code='409'>Conflict</error>
</presence>

we test for the receipt of a <presence/> element so formed:

def presenceCB(con, prs):

    # deal with nickname conflict in room
    if str(prs.getFrom()) == roomjid and prs.getType() == 'error':
        prsnode = prs.asNode()
        error = prsnode.getTag('error')
        if error:
          if (error.getAttr('code') == '409'):
              print "cannot join room - conflicting nickname"
              con.disconnect()
              sys.exit(0)

The <presence/> element will appear to be sent from the JID that we constructed for our initial room entry negotiation (in the roomjid variable further down in the script), for example, in our case:

jdev@conference.jabber.org/kassist

We compare this value to the value of the incoming <presence/>'s from attribute, and also make sure that the type attribute is set to "error".

If it is, we want to extract the details from the <error/> tag that will be contained as a direct child of the <presence/>. The JabberPy library doesn't offer a direct high-level function to get at this tag from the Presence object (in prs), but we can strip away the presence object "mantle" and get at the underlying object, which is a neutral "node"—a Jabber element, or XML fragment, without any pre-conceived ideas of what it is (and therefore without any accompanying high-level methods such as getBody() or setPriority(). [6]

The asNode() method gives us what we need - a Protocol object representation of our <presence/> element. From this we can get to the <error/> tag and its contents. If we find that we do have a nickname conflict, we abort by disconnecting from the Jabber server and ending the script.

The general idea is that this script will run indefinitely and notify the users on a continuous basis. No presence subscription relationships are built (mostly to keep the script small and simple; you could adapt the mechanism from the recipe in the section called Presence-sensitive CVS notification in Chapter 7 if you wanted to make this script sensitive to presence) and so notifications will get queued up for the user if he is offline. [7] This makes a lot of sense for the most part; I still want to have the script send me notifications even if I'm offline. However, consider that the script could be sent a command, to watch for a keyword or phrase, from a user within the room. We would receive the command from a JID like this:

jdev@conference.jabber.org/nickname

This is a "transient" JID, in that it represents a user's presence in the jdev room for a particular session. If a word is spotted by the script hours or days later, there's a good chance that the user has left the room, making the JID invalid as a recipient—although the JID is technically valid and will reach the conferencing component, there will be no real user JID that it is paired up with. Potentially worse, the room occupant's identity JID may be assigned to someone else at a later stage, if the original user left, and a new user entered choosing the same nick as the original user had chosen. the sidebar Transient JIDs and non-existent JIDs discusses the difference between a "transient" JID and a non-existent JID.

So as soon as we notice a user leave the room we're in, which will be indicated through a <presence/> element conveying that occupant's unavailability, we should remove any watched-for words and phrases from our hash:

    # remove keyword list for groupchat correspondent
    if prs.getType() == 'unavailable':
        jid = str(prs.getFrom())
        if keywords.has_key(jid):
            del keywords[jid]

As before, we obtain the string representation of the JID using the str() function on the JID object that represents the presence element's sender, obtained via the getFrom() method.