search

guyzmo / event-source-library

Python Event Source Library
GNU General Public License v3.0
35 stars 9 forks source link

readme

README: Event Source Library for Python

This library implements W3C Draft's on event-source:

It enables a halfduplex communication from server to client, but initiated by the client, through standard HTTP(S) communication.

Dependances

Usage

  1. Launch the server::

    eventsource-server -P 8888 -i -k 50000

  2. Launch the client::

    eventsource-client 42:42:42:42:42:42 -r 5000 -P 8888

  3. Send requests::

    eventsource-request 42:42:42:42:42:42 ping "42" eventsource-request 42:42:42:42:42:42 close

Command Line arguments

Install

You can install it by getting it from pypi::

pip install event-source-library

or by getting this repository and install it manually::

python setup.py install

Development

To develop, you can use buildout::

pip install zc.buildout # if you haven't got it
buildout
ls bin/

Or you can do:

python setup.py develop

which will deploy the commands globally like an install, but still linked to the current sources.

Integrate

On the server side, basically all you have to do is to add the following to your code::

from eventsource import listener

application = tornado.web.Application([
    (r"/(.*)/(.*)", listener.EventSourceHandler, 
                                      dict(event_class=EVENT,
                                           keepalive=KEEPALIVE)),
])

application.listen(PORT)
tornado.ioloop.IOLoop.instance().start()

where:

See http://www.tornadoweb.org/en/stable/web.html#application-configuration for more details.

Extend

To extend the behaviour of the event source library, without breaking eventsource definition, the Event based classes implements all processing elements that shall be done on events.

There is two abstract classes that defines Event:

here is an example to create a new Event that takes multiline data and join it in a one line string seperated with semi-colons.

::

class OneLineEvent(Event):
    ACTIONS = ["ping",Event.FINISH]

    """Property to enable multiline output of the value"""
    def get_value(self):
        # replace carriage returns by semi-colons
        # this method shall always return a list (even if one value)
        return [";".join([line for line in self._value.split('\n')])]

    value = property(get_value,set_value)

And now, I want to add basic id support to OneLineEvent, in OneLineEventId, nothing is easier ::

class OneLineEventId(OneLineEvent,EventId):
    id = property(EventId.get_value)

Or if I want the id to be a timestamp::

import time
class OneLineTimeStampEvent(OneLineEvent):
    id = property(lambda s: "%f" % (time.time(),))

You can change the behaviour of a few things in a Event-based class:

To change the way events are generated, you can directly call EventSourceHandler.buffer_event() to create a new event to be sent. But the post action is best, at least while WSGI can't handle correctly long polling connections.

Licensing

::

Python Event Source Library

(c) 2012 Bernard Pratz
Patches by Ian Whyman, Коренберг Марк and Max Suraev

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

EOF