docs/main/FeedStream.rst | 89 +++++++++++++++++++++++++++++++++++++++++++ docs/main/FeedWidget.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++ docs/main/Feeds.rst | 97 +---------------------------------------------- 3 files changed, 188 insertions(+), 93 deletions(-)
New commits: commit 6a7b5cbd8122f2ea27a9e456e964721b5ed12a24 Author: Luke Macken lmacken@redhat.com Date: Mon Feb 7 20:21:39 2011 -0500
Document our moksha feed aggregator and new post-processing feed hooks
diff --git a/docs/main/FeedStream.rst b/docs/main/FeedStream.rst new file mode 100644 index 0000000..89a6741 --- /dev/null +++ b/docs/main/FeedStream.rst @@ -0,0 +1,89 @@ +The Moksha Feed Stream +---------------------- + +The ``moksha.feeds`` app provides a moksha Producer_ that will handle +automatically fetching, parsing, and caching feeds. Once installed, the Moksha Feed Stream will be run by the MokshaHub_. + +It will automatically fetch all feeds used by the Moksha :class:`Feed` object, +as well as all feeds listed in a ``feeds.txt`` file, if one exists. + +Installing the ``moksha.feeds`` app +----------------------------------- + +Currently the easiest way to install the app is from the moksha git repository + +.. code-block:: bash + + $ git clone git://git.fedorahosted.org/git/moksha + $ cd moksha/apps/feeds + + +From here, if you are running Moksha from an RPM installation: + +.. code-block:: bash + + $ paver reinstall + +Or, if you're running from a virtualenv installation: + +.. code-block:: bash + + $ paver install + +Configuring the Moksha Feed Aggregator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The feed app can be configured with the following options in your config file: + +.. code-block:: python + + # Number of seconds between polling feeds + feed.poll_frequency = 900 + + # Where to store the feed caches. Defaults to an in-memory cache. + #feed_cache = sqlite:///%(here)s/feeds.db + + # Max age (in seconds) of each feed in the cache + feed.max_age = 300 + + # Timeout in seconds for the web request + feed.timeout = 60 + + # The number of simultaneous connections + feed.deferred_groups = 3 + + +Performing post-processing on feed entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All new feed entries for a given ``$URL`` are sent to the ``moksha.feeds.$URL`` +message topic. By default only the title and url of the entry are sent to the +message broker. However, Moksha provides a simple API for writing +post-processing plug-ins that can modify the feed before it is sent to any +:doc:`LiveWidgets` or :doc:`Consumers`. + +.. code-block:: python + + def process_feed_entry(entry): + """ This method is called by the Moksha Feed Streamer with each feed entry. + + Here is where we do post-processing on the entry before it gets serialized + to JSON and send to our message broker, and then the users. + + :entry: A :mod:`feedparser` feed object + """ + return dict(author=entry['author'], + author_link=entry['author_detail']['href'], + content=entry['content'][0]['value'], + author_avatar=entry['source']['icon']) + +Then you simply plug this method into the ``moksha.feeds.post_processor`` entry-point: + +.. code-block:: python + + setup(... + entry_points=""" + [moksha.feeds.post_processor] + myfeedprocessor = myapp.feed_processor:process_feed_entry + """ + ) diff --git a/docs/main/FeedWidget.rst b/docs/main/FeedWidget.rst new file mode 100644 index 0000000..4838e8c --- /dev/null +++ b/docs/main/FeedWidget.rst @@ -0,0 +1,95 @@ +The Moksha Feed Widget +---------------------- + +.. autoclass:: moksha.api.widgets.feed.Feed + :members: + +.. widgetbrowser:: moksha.widgets.demos.FeedDemo + :tabs: demo, source, template + :size: large + +Using the Feed widget +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + from moksha.api.widgets.feed import Feed + feed = Feed('myfeed') + feed(url='http://lewk.org/rss') + +Rendering a url with the Feed object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + feed = Feed('myfeed') + feed(url='http://lewk.org/rss') + +.. note:: + Usually you would instantiate a single Feed object somewhere in your + project, and just call it with a `url` when rendering it in your templates. + +Subclassing +~~~~~~~~~~~ + +.. code-block:: python + + class MyFeed(Feed): + url = 'http://foo.com/feed.xml' + + myfeed = MyFeed() + myfeed() # renders the widget, usually done in the template + +As ToscaWidget children +~~~~~~~~~~~~~~~~~~~~~~~ + +By defining your Feeds as children to a widget, ToscaWidgets will automatically +handle setting a unique id for your Feed object, as well as giving you the +ability access it in your template from the `c` context object. + +.. code-block:: python + + from tw.api import Widget + from moksha.api.widgets.feed import Feed + + class MyWidget(Widget): + myfeedurl = 'http://foo.com/feed.xml' + children = [Feed('myfeed', url=myfeedurl)] + template = "${c.myfeed()}" + +As a generator +~~~~~~~~~~~~~~ + +.. code-block:: python + + feed = Feed('myfeed', url='http://foo.com/feed.xml') + print '%d entries' % feed.num_entries() + for entry in feed.iterentries(): + print entry.title + +Using the moksha feed cache by hand +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The moksha Feed widget automatically handles fetching and caching your feeds +using the global moksha feed cache. The moksha middleware automatically +handles setting up this object, and making it available for all of the +applications and widgets. Moksha utilizes `Doug Hellmann's feedcache module http://www.doughellmann.com/projects/feedcache`_, which intelligently handles +all of the hard work for us. + +Here is an example of using the feed cache to manually fetch a feed. + + +.. code-block:: python + + import moksha + feed = moksha.feed_cache.fetch('http://foo.com/feed.xml') + for entry in feed.entries: + print entry + +.. note:: + The moksha.feed_cache object is a + :class:`paste.registry.StackedObjectProxy` instance, and is setup by the + :class:`moksha.middleware.MokshaMiddleware` before each request reaches + your application. Thus, it only works during requests and cannot be + used without using the MokshaMiddleware. + diff --git a/docs/main/Feeds.rst b/docs/main/Feeds.rst index b6e7bdb..24256b2 100644 --- a/docs/main/Feeds.rst +++ b/docs/main/Feeds.rst @@ -11,97 +11,8 @@ When used within the Moksha Platform, the Feed object will utilize the central global `moksha.feed_cache`. When used outside of the platform, it will automatically use a local sqlite database cache.
-The Moksha Feed Widget ----------------------- +.. toctree:: + :maxdepth: 2
-.. autoclass:: moksha.api.widgets.feed.Feed - :members: - -.. widgetbrowser:: moksha.widgets.demos.FeedDemo - :tabs: demo, source, template - :size: large - -Using the Feed widget -~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: python - - from moksha.api.widgets.feed import Feed - feed = Feed('myfeed') - feed(url='http://lewk.org/rss') - -Rendering a url with the Feed object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: python - - feed = Feed('myfeed') - feed(url='http://lewk.org/rss') - -.. note:: - Usually you would instantiate a single Feed object somewhere in your - project, and just call it with a `url` when rendering it in your templates. - -Subclassing -~~~~~~~~~~~ - -.. code-block:: python - - class MyFeed(Feed): - url = 'http://foo.com/feed.xml' - - myfeed = MyFeed() - myfeed() # renders the widget, usually done in the template - -As ToscaWidget children -~~~~~~~~~~~~~~~~~~~~~~~ - -By defining your Feeds as children to a widget, ToscaWidgets will automatically -handle setting a unique id for your Feed object, as well as giving you the -ability access it in your template from the `c` context object. - -.. code-block:: python - - from tw.api import Widget - from moksha.api.widgets.feed import Feed - - class MyWidget(Widget): - myfeedurl = 'http://foo.com/feed.xml' - children = [Feed('myfeed', url=myfeedurl)] - template = "${c.myfeed()}" - -As a generator -~~~~~~~~~~~~~~ - -.. code-block:: python - - feed = Feed('myfeed', url='http://foo.com/feed.xml') - print '%d entries' % feed.num_entries() - for entry in feed.iterentries(): - print entry.title - -Using the moksha feed cache by hand -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The moksha Feed widget automatically handles fetching and caching your feeds -using the global moksha feed cache. The moksha middleware automatically -handles setting up this object, and making it available for all of the -applications and widgets. Moksha utilizes `Doug Hellmann's feedcache module http://www.doughellmann.com/projects/feedcache`_, which intelligently handles -all of the hard work for us. - -Here is an example of using the feed cache to manually fetch a feed. - - -.. code-block:: python - - import moksha - feed = moksha.feed_cache.fetch('http://foo.com/feed.xml') - for entry in feed.entries: - print entry - -.. note:: - The moksha.feed_cache object is a - :class:`paste.registry.StackedObjectProxy` instance, and is setup by the - :class:`moksha.middleware.MokshaMiddleware` before each request reaches - your application. Thus, it only works during requests and cannot be - used without using the MokshaMiddleware. + FeedWidget + FeedStream
moksha-commits@lists.fedorahosted.org