Permalink
Browse files

updated docstrings

  • Loading branch information...
1 parent dbf205a commit 4979668281757a7af1a0f3930df96d8edea007de @guyzmo committed May 26, 2012
Showing with 48 additions and 16 deletions.
  1. +25 −1 eventsource/client.py
  2. +23 −15 eventsource/listener.py
View
@@ -20,7 +20,15 @@ def __repr__(self):
return "Event<%s,%s,%s>" % (str(self.id), str(self.name), str(self.data.replace('\n','\\n')))
class EventSourceClient(object):
- def __init__(self,url,action,target,callback=None,retry=-1):
+ def __init__(self,url,action,target,callback=None,retry=0):
+ """
+ Build the event source client
+ :param url: string, the url to connect to
+ :param action: string of the listening action to connect to
+ :param target: string with the listening token
+ :param callback: function with one parameter (Event) that gets called for each received event
+ :param retry: timeout between two reconnections (0 means no reconnection)
+ """
self._url = "http://%s/%s/%s" % (url,action,target)
AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")
self.http_client = AsyncHTTPClient()
@@ -36,6 +44,9 @@ def __init__(self,url,action,target,callback=None,retry=-1):
self.retry_timeout = int(retry)
def poll(self):
+ """
+ Function to call to start listening
+ """
if self.retry_timeout == 0:
self.http_client.fetch(self.http_request, self.handle_request)
IOLoop.instance().start()
@@ -45,10 +56,19 @@ def poll(self):
time.sleep(self.retry_timeout/1000)
def end(self):
+ """
+ Function to call to end listening
+ """
self.retry_timeout=0
IOLoop.instance().stop()
def handle_stream(self,message):
+ """
+ Acts on message reception
+ :param message: string of an incoming message
+
+ parse all the fields and builds an Event object that is passed to the callback function
+ """
event = Event()
for line in message.strip('\r\n').split('\r\n'):
(field, value) = line.split(":",1)
@@ -77,6 +97,10 @@ def handle_stream(self,message):
def handle_request(self,response):
+ """
+ Function that gets called on non long-polling actions,
+ on error or on end of polling.
+ """
if response.error:
log.error(response.error)
else:
View
@@ -1,7 +1,15 @@
-# resources:
-# * http://stackoverflow.com/questions/10665569/websocket-event-source-implementation-to-expose-a-two-way-rpc-to-a-python-dj
-# * http://stackoverflow.com/questions/8812715/using-a-simple-python-generator-as-a-co-routine-in-a-tornado-async-handler
-# * http://dev.w3.org/html5/eventsource/#event-stream-interpretation
+"""
+.. module:: listener
+:platform: Unix
+:synopsis: This module provides an eventsource listener based on tornado
+
+.. moduleauthor:: Bernard Pratz <guyzmo@hackable-devices.org>
+
+.. resources::
+ * http://stackoverflow.com/questions/10665569/websocket-event-source-implementation-to-expose-a-two-way-rpc-to-a-python-dj
+ * http://stackoverflow.com/questions/8812715/using-a-simple-python-generator-as-a-co-routine-in-a-tornado-async-handler
+ * http://dev.w3.org/html5/eventsource/#event-stream-interpretation
+"""
import sys
import time
@@ -49,9 +57,9 @@ def set_value(self, v):
def __init__(self, target, action, value=None):
"""
Creates a new Event object with
- @param target a string matching an open channel
- @param action a string matching an action in the ACTIONS list
- @param value a value to be embedded
+ :param target: a string matching an open channel
+ :param action: a string matching an action in the ACTIONS list
+ :param value: a value to be embedded
"""
self.target = target
self.action = action
@@ -132,7 +140,7 @@ def push_keepalive(self):
def push(self, event):
"""
For a given event, write event-source outputs on current handler
- @param event Event based incoming event
+ :param event: Event based incoming event
"""
log.debug("push(%s,%s,%s)" % (event.id,event.action,event.value))
if hasattr(event, "id"):
@@ -150,15 +158,15 @@ def buffer_event(self, target, action, value=None):
"""
creates and store an event for the target
- @param target string identifying current target
- @param action string matching one of Event.ACTIONS
- @param value string containing a value
+ :param target: string identifying current target
+ :param action: string matching one of Event.ACTIONS
+ :param value: string containing a value
"""
self._events[target].append(self._event_class(target, action, value))
def is_connected(self, target):
"""
- @param target string identifying a given target
+ :param target: string identifying a given target
@return true if target is connected
"""
return target in self._connected.values()
@@ -167,7 +175,7 @@ def set_connected(self, target):
"""
registers target as being connected
- @param target string identifying a given target
+ :param target: string identifying a given target
this method will add target to the connected list,
and create an empty event buffer
@@ -224,8 +232,8 @@ def post(self,action,target):
"""
Triggers an event
- @param action string defining the type of event
- @param target string defining the target handler to send it to
+ :param action: string defining the type of event
+ :param target: string defining the target handler to send it to
this method will look for the request body to get post's data.
"""

0 comments on commit 4979668

Please sign in to comment.