diff --git a/feedgenerator/__init__.py b/feedgenerator/__init__.py index b7892b0..0c10096 100644 --- a/feedgenerator/__init__.py +++ b/feedgenerator/__init__.py @@ -1,10 +1,107 @@ # -*- coding: utf-8 -*- """ + ============= feedgenerator - ~~~~~~~~~~~~~ + ============= - This module can be used to wenerate web feeds in both ATOM and RSS format. + This module can be used to generate web feeds in both ATOM and RSS format. + They included PodcastGenerator furthermore includes all of Apples RSS + extension for Podcasts. :copyright: 2013 by Lars Kiesow :license: FreeBSD and LGPL, see LICENSE for more details. + + + ------------- + Create a Feed + ------------- + + To create a feed simply instanciate the FeedGenerator class and insert some + data:: + + >>> from feedgenerator.feed import FeedGenerator + >>> fg = FeedGenerator() + >>> fg.id('http://lernfunk.de/media/654321') + >>> fg.title('Some Testfeed') + >>> fg.author( {'name':'John Doe','email':'john@example.de'} ) + >>> fg.link( href='http://example.com', rel='alternate' ) + >>> fg.logo('http://ex.com/logo.jpg') + >>> fg.subtitle('This is a cool feed!') + >>> fg.link( href='http://larskiesow.de/test.atom', rel='self' ) + >>> fg.language('en') + + Note that for the methods which set fields that can occur more than once in + a feed you can use all of the following ways to provide data: + + - Provide the data for that element as keyword arguments:: + - Provide the data for that element as dictionary:: + - Provide a list of dictionaries with the data for several elements:: + + Example:: + + >>> fg.contributor( name='John Doe', email='jdoe@example.com' ) + >>> fg.contributor({'name':'John Doe', 'email':'jdoe@example.com'}) + >>> fg.contributor([{'name':'John Doe', 'email':'jdoe@example.com'}, ...]) + + ----------------- + Generate the Feed + ----------------- + + After that you can generate both RSS or ATOM by calling the respective method:: + + >>> atomfeed = fg.atom_str(pretty=True) # Get the ATOM feed as string + >>> rssfeed = fg.rss_str(pretty=True) # Get the RSS feed as string + >>> fg.atom_file('atom.xml') # Write the ATOM feed to a file + >>> fg.rss_file('rss.xml') # Write the RSS feed to a file + + + ---------------- + Add Feed Entries + ---------------- + + To add entries (items) to a feed you need to create new FeedEntry objects + and append them to the list of entries in the FeedGenerator. The most + convenient way to go is to use the FeedGenerator itself for the + instantiation of the FeedEntry object:: + + >>> fe = fg.add_entry() + >>> fe.id('http://lernfunk.de/media/654321/1') + >>> fe.title('The First Episode') + + The FeedGenerators method add_entry(...) without argument provides will + automaticall generate a new FeedEntry object, append it to the feeds + internal list of entries and return it, so that additional data can be + added. + + ----------------- + Produce a Podcast + ----------------- + + A podcast is an RSS feed with some additional elements for ITunes. The + feedgenerator has a PodcastGenerator class as extension to the default + FeedGenerator which you can use to set these additional fields. + + To produce a podcast simply do something like this:: + + >>> from feedgenerator.podcast import PodcastGenerator + >>> fg = PodcastGenerator() + ... + >>> fg.podcast_str(pretty=True) + >>> fg.podcast_file('podcast.xml') + + For the episodes of the podcast you should also use PodcastEntry instead of + FeedEntry. However, if you use the add_entry(...) method to generator the + entry objects, it will take care of that for you. + + Of cause you can still produce a normat ATOM or RSS feed, even if you use + the PodcastGenerator using the {atom,rss}_{str,file} methods. + + --------------------- + Testing the Generator + --------------------- + + You can test the module by simply executing:: + + %> pythom -m feedgenerator + """ diff --git a/feedgenerator/__main__.py b/feedgenerator/__main__.py index e375b68..180e2af 100644 --- a/feedgenerator/__main__.py +++ b/feedgenerator/__main__.py @@ -20,13 +20,14 @@ if __name__ == '__main__': sys.argv[1].endswith('rss') \ or sys.argv[1].endswith('atom') \ or sys.argv[1].endswith('podcast') ): - print 'Usage: %s ( .atom | atom | .rss | rss )' % \ + print 'Usage: %s ( .atom | atom | .rss | rss | podcast )' % \ 'pythom -m feedgenerator' print '' print ' atom -- Generate ATOM test output and print it to stdout.' print ' rss -- Generate RSS test output and print it to stdout.' print ' .atom -- Generate ATOM test feed and write it to file.atom.' print ' .rss -- Generate RSS test teed and write it to file.rss.' + print ' podcast -- Generator Podcast test output and print it to stdout.' print '' exit()