Awasu » Writing Awasu extensions: Generating the feed
Monday 6th April 2015 10:00 AM []

In this tutorial, we'll write a plugin channel that demonstrates how easy it is to get information into Awasu. Since the purpose of this exercise is to show what needs to be done to write an extension, we'll keep it simple and write something that monitors files in a directory for changes.

Installing the awasu_tools library

To help with the process of writing extensions, a Python module called awasu-tools has been made available.

If you're online, the easiest way to install it is to get it directly from PyPI:

    pip install awasu-tools # nb: has a hyphen, not an underscore

Alternatively, you can download it from GitHub and install it locally e.g.

    pip install awasu_tools.zip
As always, the use of virtual environments is strongly recommended, to keep your projects and their dependencies separate from each other.


Creating the feed

awasu_tools comes with classes that make it really easy to generate feeds.

from awasu_tools.feed import Feed , FeedItem

# get our parameters 
dir_to_monitor = "r:/dirmon-test"

# initialize the feed
feed = Feed( 
    "Directory Monitor" , 
    dir_to_monitor ,
    description = "Monitoring {}".format( dir_to_monitor ) ,
)

# output the feed XML
print feed.get_xml()

We import the Feed class, instantiate it with a few key parameters [1]For the moment, we hard-code the directory to be monitored, but we'll change this later to be user-configurable., then print out its feed XML:

Adding feed items

Adding feed items to our feed is just as easy:

# add a few dummy feed items
feed.feed_items.append(
    FeedItem( 
        "feed item 1" , 
        "http://test.com/feed-item-1" , 
        "This is feed item 1." 
    )
)
feed.feed_items.append(
    FeedItem( 
        "feed item 2" , 
        "http://test.com/feed-item-2" , 
        "This is feed item 2." 
    )
)

Printing out the feed XML now includes the feed items we added:

Generating the feed

Let's replace the dummy feed items with the real thing:

from awasu_tools import make_iso8601_timestamp

# generate the feed items
for fname in os.listdir(dir_to_monitor) :
    # check if the next entry is a file
    fname_abs = os.path.abspath( os.path.join( dir_to_monitor , fname ) )
    if not os.path.isfile(fname_abs) : 
        continue
    # generate the next feed item
    updated_time = os.stat( fname_abs )[ stat.ST_MTIME ]
    feed.feed_items.append(
        FeedItem( 
            fname ,
            "file:///{}".format( fname_abs ) ,
            content = "Last modified: {}".format( 
                time.strftime( "%c" , time.localtime(updated_time) ) 
            ) ,
            updated_time = make_iso8601_timestamp( updated_time ) ,
        )
    )

We iterate through all the files in the specified directory, adding a new FeedItem for each one [2]This code, of course, doesn't handle the case of files being deleted. This plugin is not production quality, it's being presented here as an example of how to write an extension. Bringing it up to release quality is left, as my maths professors were fond of saying, left as an exercise for the reader 🙂 . If the file is changed, the feed item's content and updated time will change, causing Awasu to flag a revised item [3]Note that since the feed items don't specify a unique ID for each item, Awasu will identify them via their URL, which will be all different. However, if a feed item changes, Awasu will not treat it as a new feed item, just a revised version of an old one (since its URL has not changed). You will get best results if you configure the Awasu channel to track revised items, so that it will show the revisions separately..

This outputs feed XML like this:

Download the source code here.



   [ + ]

1. For the moment, we hard-code the directory to be monitored, but we'll change this later to be user-configurable.
2. This code, of course, doesn't handle the case of files being deleted. This plugin is not production quality, it's being presented here as an example of how to write an extension. Bringing it up to release quality is left, as my maths professors were fond of saying, left as an exercise for the reader 🙂
3. Note that since the feed items don't specify a unique ID for each item, Awasu will identify them via their URL, which will be all different. However, if a feed item changes, Awasu will not treat it as a new feed item, just a revised version of an old one (since its URL has not changed). You will get best results if you configure the Awasu channel to track revised items, so that it will show the revisions separately.
Have your say