Introduction
============

``horae.subscription`` provides generic subscription functionality for the
Horae resource planning system.

Usage
=====

Objects marked with the ``horae.subscription.interfaces.ISubscribeable``
interfaces receive the functionality of being subscribed to. Which means
a viewlet is displayed rendering all subscribers and a button to subscribe
and unsubscribe if an adapter implementing
``horae.subscription.interfaces.ISubscriber`` and adapting the request is available.

The subscribers of an ``horae.subscription.interfaces.ISubscribeable`` may be
notified by using the ``horae.subscription.interfaces.ISubscription`` adapter.
First some basic implementations are required::

    import grok
    
    from horae.subscription import interfaces
    
    class Subscriber(object):
        grok.implements(interfaces.ISubscriber)
        
        def __init__(self, id, name, url=None):
            self.id = id
            self.name = name
            self.url = url
    
        def notify(self, message, subject):
            """ Sends the message to the subscriber
            """
            print self.name + ': (' + subject + ') ' + subject
    
        def available(self, context):
            """ Whether this subscriber is currently available or not
            """
            return True
    
    class Message(object):
        grok.implements(interfaces.IMessage)
        
        def __init__(self, subject, message):
            self._subject = subject
            self._message = message
    
        def subject(self):
            """ Returns the subject of the notification to be sent
            """
            return self._subject
    
        def message(self, html=False):
            """ Returns the notification message to be sent
            """
            return self._message
    
    class Subscribeable(grok.Model):
        grok.implements(interfaces.ISubscribeable)

With those implementations in place some subscriptions may be made and
a message may be sent to them.

First we create a subscribeable object::

    >>> subscribeable = Subscribeable()

Now we create two subscribers and subscribe them to the subscribeable::

    >>> subscriber1 = Subscriber('jsmith', 'John Smith')
    >>> subscriber2 = Subscriber('jdoe', 'John Doe')
    >>> subscription = interfaces.ISubscription(subscribeable)
    >>> subscription.subscribe(subscriber1)
    >>> subscription.subscribe(subscriber2)

And send out a message::

    >>> message = Message('Test subject', 'Test message')
    >>> sent, failed = subscription.notify(message)
    John Smith: (Test subject) Test message
    John Doe: (Test subject) Test message
    >>> sent
    2
    >>> failed
    0

Unsubscription is also done using the subscription adapter::

    >>> subscription.unsubscribe(subscriber2.id)
    >>> sent, failed = subscription.notify(message)
    John Smith: (Test subject) Test message
    >>> sent
    1
    >>> failed
    0

Dependencies
============

Horae
-----

* `horae.core <http://pypi.python.org/pypi/horae.core>`_
* `horae.layout <http://pypi.python.org/pypi/horae.layout>`_
* `horae.ticketing <http://pypi.python.org/pypi/horae.ticketing>`_

Third party
-----------

* `grok <http://pypi.python.org/pypi/grok>`_
