Metadata-Version: 1.0
Name: SubHub
Version: 0.1.0
Summary: A simple personal PSHB hub for use in Django projects for your own blog. Doesn't serve as a public hub for publishers, hence just "SubHub".
Home-page: https://launchpad.net/subhub
Author: Ivan Sagalaev
Author-email: Maniac@SoftwareManiacs.Org
License: LICENSE.txt
Description: ======
        SubHub
        ======
        
        SubHub is a Django application that implements a `PubSubHubBub`_ hub. Think
        of it as a push mechanism that your personal site uses to notify subscribers
        about changes in feeds that your site publishes.
        
        .. note:: SubHub works only for Atom feeds. Which you should use anyway since
        today there are no more reasons left to use actual RSS format for feeds.
        
        This hub is not a standalone daemon that runs alongside your Django project.
        It works as a library code sending notifications whenever you hit a "Publish"
        button. It does, however, requires a cron job to process pending subscriptions
        and failed notifications.
        
        .. _PubSubHubBub: http://code.google.com/p/pubsubhubbub/
        
        
        Installation
        ============
        
        1. Install SubHub using your favorite package manager or simply with ``python
        setup.py install``.
        
        2. Include it "subhub" into INSTALLED_APPS in your Django settings and run
        ``./manage.py syncdb`` to create new tables.
        
        3. Include SubHub urls into your project's urlconf under some sensible name::
        
        urlpatterns = patterns('',
        ...
        (r'^hub/', include('subhub.urls')),
        )
        
        4. Setup a cron job that will process pending subscriptions and distribute
        failed notifications::
        
        # Process subscriptions every 3 hours
        0    */3  * * *   user  /path/to/manage.py subhub_maintenance --subscribe
        
        # Distribute notifications every 15 minutes
        */15 *    * * *   user  /path/to/manage.py subhub_maintenance --distribute
        
        
        Announcing your hub
        ===================
        
        In order to tell your potential subscribers that your feeds use PubSubHubBub
        notifications you should include a link to a SubHub subscription view into
        your Atom feeds. It looks a bit heavy but don't let it scare you off!
        
        First thing to do is to subclass Django's built-in Atom feed generator and
        teach it to look for hub links defined in your specific feed definitions::
        
        from django.utils.feedgenerator import Atom1Feed
        
        class HubAtom1Feed(Atom1Feed):
        def add_root_elements(self, handler):
        super(HubAtom1Feed, self).add_root_elements(handler)
        hub_link = self.feed.get('hub_link')
        if hub_link is not None:
        handler.addQuickElement(u'link', '', {
        u'rel': u'hub',
        u'href': hub_link,
        })
        
        Then in each your feed for which you want to use notifications define a link::
        
        from django.contrib.syndication import views
        
        class MyBlogFeed(views.Feed):
        feed_type = HubAtom1Feed
        
        def feed_extra_kwargs(self, obj):
        return {
        'hub_link': absolute_url(reverse('subhub-hub')),
        }
        
        Chances are that you already have a function like ``absolute_url`` in your
        project. It should make an URL absolute adding a scheme and a domain.
        
        
        Publishing new and changed items
        ================================
        
        To publish newly created or updated post you call function ``subhub.publish``
        passing it two parameters:
        
        - a list of feeds ("topics" in PubSubHubBub parlance) that this post appears in
        - an entry_id for a post which in most cases is its absolute URL
        
        Example::
        
        import subhub
        
        class Post(models.Model):
        
        def save(self, **kwargs):
        super(Post, self).save(**kwargs)
        if self.published:
        if transaction.is_managed():
        transaction.commit()
        topics = ['/blog/feed/'] # don't hardcode URLs, use 'reverse'
        subhub.publish(
        [absolute_url(t) for t in topics],
        absolute_url(self.get_absolute_url()),
        )
        
        You can call "publish" from anywhere you find suitable. Just make sure that
        before the call you commit a DB transaction if you use one. This is needed
        because SubHub will make a separate HTTP request into your own server to fetch
        an updated feed.
        
Platform: UNKNOWN
