Added documentation to events

docs/source/events.rst

@@ -0,0 +1,28 @@
+Events
+======
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Events:
+
+    platypush/events/assistant.rst
+    platypush/events/button.flic.rst
+    platypush/events/geo.rst
+    platypush/events/http.rst
+    platypush/events/http.rss.rst
+    platypush/events/midi.rst
+    platypush/events/music.rst
+    platypush/events/path.rst
+    platypush/events/ping.rst
+    platypush/events/pushbullet.rst
+    platypush/events/scard.rst
+    platypush/events/sensor.rst
+    platypush/events/sensor.ir.rst
+    platypush/events/sensor.leap.rst
+    platypush/events/sensor.light.rst
+    platypush/events/serial.rst
+    platypush/events/video.rst
+    platypush/events/weather.rst
+    platypush/events/web.rst
+    platypush/events/web.widget.rst
+

docs/source/index.rst

@@ -7,6 +7,7 @@ Platypush
 
     backends
     plugins
+    events
 
 Indices and tables
 ==================

docs/source/platypush/events/assistant.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.assistant``
+=====================================
+
+.. automodule:: platypush.message.event.assistant
+    :members:
+

docs/source/platypush/events/button.flic.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.button.flic``
+=======================================
+
+.. automodule:: platypush.message.event.button.flic
+    :members:
+

docs/source/platypush/events/geo.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.geo``
+===============================
+
+.. automodule:: platypush.message.event.geo
+    :members:
+

docs/source/platypush/events/http.rss.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.http.rss``
+====================================
+
+.. automodule:: platypush.message.event.http.rss
+    :members:
+

docs/source/platypush/events/http.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.http``
+================================
+
+.. automodule:: platypush.message.event.http
+    :members:
+

docs/source/platypush/events/midi.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.midi``
+================================
+
+.. automodule:: platypush.message.event.midi
+    :members:
+

docs/source/platypush/events/music.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.music``
+=================================
+
+.. automodule:: platypush.message.event.music
+    :members:
+

docs/source/platypush/events/path.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.path``
+================================
+
+.. automodule:: platypush.message.event.path
+    :members:
+

docs/source/platypush/events/ping.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.ping``
+================================
+
+.. automodule:: platypush.message.event.ping
+    :members:
+

docs/source/platypush/events/pushbullet.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.pushbullet``
+======================================
+
+.. automodule:: platypush.message.event.pushbullet
+    :members:
+

docs/source/platypush/events/scard.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.scard``
+=================================
+
+.. automodule:: platypush.message.event.scard
+    :members:
+

docs/source/platypush/events/sensor.ir.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.sensor.ir``
+=====================================
+
+.. automodule:: platypush.message.event.sensor.ir
+    :members:
+

docs/source/platypush/events/sensor.leap.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.sensor.leap``
+=======================================
+
+.. automodule:: platypush.message.event.sensor.leap
+    :members:
+

docs/source/platypush/events/sensor.light.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.sensor.light``
+========================================
+
+.. automodule:: platypush.message.event.sensor.light
+    :members:
+

docs/source/platypush/events/sensor.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.sensor``
+==================================
+
+.. automodule:: platypush.message.event.sensor
+    :members:
+

docs/source/platypush/events/serial.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.serial``
+==================================
+
+.. automodule:: platypush.message.event.serial
+    :members:
+

docs/source/platypush/events/video.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.video``
+=================================
+
+.. automodule:: platypush.message.event.video
+    :members:
+

docs/source/platypush/events/weather.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.weather``
+===================================
+
+.. automodule:: platypush.message.event.weather
+    :members:
+

docs/source/platypush/events/web.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.web``
+===============================
+
+.. automodule:: platypush.message.event.web
+    :members:
+

docs/source/platypush/events/web.widget.rst

@@ -0,0 +1,6 @@
+``platypush.message.event.web.widget``
+======================================
+
+.. automodule:: platypush.message.event.web.widget
+    :members:
+

platypush/message/event/assistant/__init__.py

@@ -23,36 +23,80 @@ class AssistantEvent(Event):
 
 
 class ConversationStartEvent(AssistantEvent):
+    """
+    Event triggered when a new conversation starts
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class ConversationEndEvent(AssistantEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a conversation ends
+    """
+
+    def __init__(self, with_follow_on_turn=False, *args, **kwargs):
+        """
+        :param with_follow_on_turn: Set to true if the conversation expects a user follow-up, false otherwise
+        :type with_follow_on_turn: str
+        """
+
+        super().__init__(*args, with_follow_on_turn=with_follow_on_turn, **kwargs)
 
 
 class ConversationTimeoutEvent(ConversationEndEvent):
+    """
+    Event triggered when a conversation times out
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class ResponseEvent(ConversationEndEvent):
+    """
+    Event triggered when a response is processed by the assistant
+    """
+
     def __init__(self, response_text, *args, **kwargs):
+        """
+        :param response_text: Response text processed by the assistant
+        :type response_text: str
+        """
+
         super().__init__(*args, response_text=response_text, **kwargs)
 
 
 class NoResponseEvent(ConversationEndEvent):
+    """
+    Event triggered when a conversation ends with no response
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class SpeechRecognizedEvent(AssistantEvent):
+    """
+    Event triggered when a speech is recognized
+    """
+
     def __init__(self, phrase, *args, **kwargs):
+        """
+        :param phrase: Recognized user phrase
+        :type phrase: str
+        """
+
         super().__init__(phrase=phrase, *args, **kwargs)
         self.recognized_phrase = phrase.strip().lower()
 
     def matches_condition(self, condition):
+        """
+        Overrides matches condition, and stops the conversation to prevent the
+        default assistant response if the event matched some event hook condition
+        """
+
         result = super().matches_condition(condition)
         if result.is_match and self._assistant and 'phrase' in condition.args:
             self._assistant.stop_conversation()
@@ -61,8 +105,17 @@ class SpeechRecognizedEvent(AssistantEvent):
 
 
 class HotwordDetectedEvent(AssistantEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a custom hotword is detected
+    """
+
+    def __init__(self, hotword=None, *args, **kwargs):
+        """
+        :param hotword: The detected user hotword
+        :type hotword: str
+        """
+
+        super().__init__(*args, hotword=hotword, **kwargs)
 
 
 # vim:sw=4:ts=4:et:

platypush/message/event/button/flic/__init__.py

@@ -2,9 +2,20 @@ from platypush.message.event import Event, EventMatchResult
 
 
 class FlicButtonEvent(Event):
-    """ Flic button event """
+    """
+    Event triggered when a sequence of user short/long presses is detected on a
+    Flic button (https://flic.io).
+    """
 
     def __init__(self, btn_addr, sequence, *args, **kwargs):
+        """
+        :param btn_addr: Physical address of the button that originated the event
+        :type btn_addr: str
+
+        :param sequence: Detected sequence, as a list of Flic button event types (either "ShortPressEvent" or "LongPressEvent")
+        :type sequence: list[str]
+        """
+
         super().__init__(btn_addr=btn_addr, sequence=sequence, *args, **kwargs)
 
 

platypush/message/event/geo.py

@@ -2,7 +2,19 @@ from platypush.message.event import Event
 
 
 class LatLongUpdateEvent(Event):
+    """
+    Event triggered upon GPS location update
+    """
+
     def __init__(self, latitude, longitude, *args, **kwargs):
+        """
+        :param latitude: GPS latitude
+        :type latitude: float
+
+        :param longitude: GPS longitude
+        :type longitude: float
+        """
+
         super().__init__(latitude=latitude, longitude=longitude, *args, **kwargs)
 
 

platypush/message/event/http/__init__.py

@@ -1,7 +1,19 @@
 from platypush.message.event import Event
 
 class HttpEvent(Event):
+    """
+    Event triggered upon HTTP request/response cycle completion
+    """
+
     def __init__(self, request, response, *args, **kwargs):
+        """
+        :param request: Reference to the original HTTP request
+        :type request: dict
+
+        :param response: The server response
+        :type response: dict
+        """
+
         super().__init__(request=request, response=response, *args, **kwargs)
 
 

platypush/message/event/http/rss.py

@@ -1,8 +1,20 @@
 from platypush.message.event.http import HttpEvent
 
 class NewFeedEvent(HttpEvent):
+    """
+    Event triggered when a monitored RSS feed has some new content
+    """
+
     def __init__(self, request, response, source_id=None, title=None,
                  digest_format=None, digest_filename=None, *args, **kwargs):
+        """
+        :param request: Original request
+        :param response: Received response
+        :param source_id: ID of the source that generated the event
+        :param title: Title of the new element
+        :param digest_format: Format of the digest - either 'html' or 'pdf', if set
+        :param digest_filename: File name of the digest, if it was dumped to file
+        """
 
         super().__init__(request=request, response=response, source_id=source_id,
                          digest_format=digest_format, title=title,

platypush/message/event/midi.py

@@ -2,7 +2,19 @@ from platypush.message.event import Event
 
 
 class MidiMessageEvent(Event):
+    """
+    Event triggered upon received MIDI message
+    """
+
     def __init__(self, message, delay=None, *args, **kwargs):
+        """
+        :param message: Received MIDI message
+        :type message: tuple[int]
+
+        :param delay: Time in seconds since the previous MIDI event (default: None)
+        :type delay: float
+        """
+
         super().__init__(*args, message=message, delay=delay, **kwargs)
 
 

platypush/message/event/music/__init__.py

@@ -9,28 +9,75 @@ class MusicEvent(Event):
 
 
 class MusicPlayEvent(MusicEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event fired upon music player playback start
+    """
+
+    def __init__(self, status=None, track=None, *args, **kwargs):
+        """
+        :param status: Player status
+        :type status: dict
+
+        :param track: Track being played
+        :type track: dict
+        """
+
+        super().__init__(*args, status=status, track=track, **kwargs)
 
 
 class MusicStopEvent(MusicEvent):
+    """
+    Event fired upon playback stop
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class MusicPauseEvent(MusicEvent):
+    """
+    Event fired upon playback paused
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class PlaylistChangeEvent(MusicEvent):
+    """
+    Event fired upon playlist change
+    """
+
     def __init__(self, changes, status=None, track=None, *args, **kwargs):
+        """
+        :param changes: List with the tracks being added or removed
+        :type changes: list
+
+        :param status: Player status
+        :type status: dict
+
+        :param track: Track being played
+        :type track: dict
+        """
+
         super().__init__(changes=changes, status=status, track=track, *args, **kwargs)
 
 
 class NewPlayingTrackEvent(MusicEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event fired when a new track is being played
+    """
+
+    def __init__(self, status=None, track=None, *args, **kwargs):
+        """
+        :param status: Player status
+        :type status: dict
+
+        :param track: Track being played
+        :type track: dict
+        """
+
+        super().__init__(*args, status=status, track=track, **kwargs)
 
 
 # vim:sw=4:ts=4:et:

platypush/message/event/path/__init__.py

@@ -2,27 +2,84 @@ from platypush.message.event import Event
 
 
 class PathOpenEvent(Event):
+    """
+    Event triggered when a monitored file is opened
+    """
+
     def __init__(self, path, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+        """
+
         super().__init__(path=path, *args, **kwargs)
 
 class PathCloseEvent(Event):
+    """
+    Event triggered when a monitored file is closed
+    """
+
     def __init__(self, path, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+        """
+
         super().__init__(path=path, *args, **kwargs)
 
 class PathCreateEvent(Event):
+    """
+    Event triggered when a monitored file is created
+    """
+
     def __init__(self, path, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+        """
+
         super().__init__(path=path, *args, **kwargs)
 
 class PathDeleteEvent(Event):
+    """
+    Event triggered when a monitored file is deleted
+    """
+
     def __init__(self, path, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+        """
+
         super().__init__(path=path, *args, **kwargs)
 
 class PathModifyEvent(Event):
+    """
+    Event triggered when a monitored file is modified
+    """
+
     def __init__(self, path, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+        """
+
         super().__init__(path=path, *args, **kwargs)
 
 class PathPermissionsChangeEvent(Event):
+    """
+    Event triggered when the permissions on a monitored file are changed
+    """
+
     def __init__(self, path, umask, *args, **kwargs):
+        """
+        :param path: File name
+        :type path: str
+
+        :param umask: New file umask
+        :type umask: int
+        """
+
         super().__init__(path=path, umask=umask, *args, **kwargs)
 
 

platypush/message/event/ping.py

@@ -2,9 +2,14 @@ from platypush.message.event import Event, EventMatchResult
 
 
 class PingEvent(Event):
-    """ Ping event """
+    """ Ping event, used for testing purposes """
 
     def __init__(self, message=None, *args, **kwargs):
+        """
+        :param message: Ping message
+        :type message: object
+        """
+
         super().__init__(message=message, *args, **kwargs)
 
 

platypush/message/event/scard.py

@@ -2,12 +2,36 @@ from platypush.message.event import Event
 
 
 class SmartCardDetectedEvent(Event):
+    """
+    Event triggered when a smart card is detected
+    """
+
     def __init__(self, atr, reader=None, *args, **kwargs):
+        """
+        :param atr: Smart card ATR (Answer To Reset)
+        :type atr: str
+
+        :param reader: Name or address of the reader that fired the event
+        :type reader: str
+        """
+
         super().__init__(atr=atr, reader=reader, *args, **kwargs)
 
 
 class SmartCardRemovedEvent(Event):
+    """
+    Event triggered when a smart card is removed
+    """
+
     def __init__(self, atr=None, reader=None, *args, **kwargs):
+        """
+        :param atr: Smart card ATR (Answer To Reset)
+        :type atr: str
+
+        :param reader: Name or address of the reader that fired the event
+        :type reader: str
+        """
+
         super().__init__(atr=atr, reader=reader, *args, **kwargs)
 
 

platypush/message/event/sensor/__init__.py

@@ -2,23 +2,49 @@ from platypush.message.event import Event
 
 
 class SensorDataChangeEvent(Event):
+    """
+    Event triggered when a sensor has new data
+    """
+
     def __init__(self, data, *args, **kwargs):
+        """
+        :param data: Sensor data
+        :type data: object
+        """
+
         super().__init__(data=data, *args, **kwargs)
         self.data = data
 
 
 class SensorDataAboveThresholdEvent(Event):
+    """
+    Event triggered when a sensor's read goes above a configured threshold
+    """
+
     def __init__(self, data, *args, **kwargs):
+        """
+        :param data: Sensor data
+        :type data: object
+        """
+
         super().__init__(data=data, *args, **kwargs)
         self.data = data
 
 
 class SensorDataBelowThresholdEvent(Event):
+    """
+    Event triggered when a sensor's read goes below a configured threshold
+    """
+
     def __init__(self, data, *args, **kwargs):
+        """
+        :param data: Sensor data
+        :type data: object
+        """
+
         super().__init__(data=data, *args, **kwargs)
         self.data = data
 
 
 # vim:sw=4:ts=4:et:
 
-

platypush/message/event/sensor/ir/__init__.py

@@ -2,18 +2,38 @@ from platypush.message.event import Event
 
 
 class IrSensorEvent(Event):
+    """
+    Base class for infrared sensor events
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class IrKeyUpEvent(IrSensorEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a key on an infrared remote is released
+    """
+
+    def __init__(self, message=None, *args, **kwargs):
+        """
+        :param message: The received infrared message
+        """
+
+        super().__init__(*args, message=message, **kwargs)
 
 
 class IrKeyDownEvent(IrSensorEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a key on an infrared remote is pressed
+    """
+
+    def __init__(self, message=None, *args, **kwargs):
+        """
+        :param message: The received infrared message
+        """
+
+        super().__init__(*args, message=message, **kwargs)
 
 
 # vim:sw=4:ts=4:et:

platypush/message/event/sensor/leap.py

@@ -2,26 +2,51 @@ from platypush.message.event import Event
 
 
 class LeapFrameEvent(Event):
+    """
+    Event triggered when a Leap Motion devices receives a new frame
+    """
+
     def __init__(self, hands, *args, **kwargs):
+        """
+        :param hands: Reference to the detected hands properties (palm and fingers X,Y,Z position, direction etc.)
+        :type hands: dict
+        """
+
         super().__init__(hands=hands, *args, **kwargs)
 
 
 class LeapFrameStartEvent(Event):
+    """
+    Event triggered when a new sequence of frames is detected by the Leap Motion sensor
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class LeapFrameStopEvent(Event):
+    """
+    Event triggered when a Leap Sensor stops detecting frames
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class LeapConnectEvent(Event):
+    """
+    Event triggered when a Leap Motion sensor is connected
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class LeapDisconnectEvent(Event):
+    """
+    Event triggered when a Leap Motion sensor is disconnected
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 

platypush/message/event/sensor/light/__init__.py

@@ -2,11 +2,19 @@ from platypush.message.event import Event
 
 
 class LightOnEvent(Event):
+    """
+    Event triggered when a light on event is detected
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class LightOffEvent(Event):
+    """
+    Event triggered when a light off event is detected
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 

platypush/message/event/serial/__init__.py

@@ -2,7 +2,19 @@ from platypush.message.event import Event
 
 
 class SerialDataEvent(Event):
+    """
+    Event fired when a serial interface (generic USB, Arduino etc.) receives new data
+    """
+
     def __init__(self, data, device=None, *args, **kwargs):
+        """
+        :param data: Received data
+        :type data: object
+
+        :param device: Source device address or name
+        :type device: str
+        """
+
         super().__init__(data=data, device=device, *args, **kwargs)
 
 

platypush/message/event/video/__init__.py

@@ -9,23 +9,49 @@ class VideoEvent(Event):
 
 
 class VideoPlayEvent(VideoEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a new video content is played
+    """
+
+    def __init__(self, video=None, *args, **kwargs):
+        """
+        :param video: File name or URI of the played video
+        :type video: str
+        """
+
+        super().__init__(*args, video=video, **kwargs)
 
 
 class VideoStopEvent(VideoEvent):
+    """
+    Event triggered when a video is stopped
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class VideoPauseEvent(VideoEvent):
+    """
+    Event triggered when a video playback is paused
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
 
 class NewPlayingVideoEvent(VideoEvent):
-    def __init__(self, *args, **kwargs):
+    """
-        super().__init__(*args, **kwargs)
+    Event triggered when a video playback is paused
+    """
+
+    def __init__(self, video=None, *args, **kwargs):
+        """
+        :param video: File name or URI of the played video
+        :type video: str
+        """
+
+        super().__init__(*args, video=video, **kwargs)
 
 
 # vim:sw=4:ts=4:et:

platypush/message/event/weather.py

@@ -1,6 +1,10 @@
 from platypush.message.event import Event
 
 class NewWeatherConditionEvent(Event):
+    """
+    Event triggered when the weather condition changes
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 

platypush/message/event/web/__init__.py

@@ -9,6 +9,17 @@ class DashboardIframeUpdateEvent(Event):
     """
 
     def __init__(self, url, width=None, height=None, timeout=None, *args, **kwargs):
+        """
+        :param url: URL to show in the iframe dashboard element
+        :type url: str
+
+        :param width: Iframe width, as int (pixels) or CSS string
+        :param height: Iframe height, as int (pixels) or CSS string
+
+        :param timeout: If set, the iframe will be closed after this time (in seconds)
+        :type timeout: float
+        """
+
         super().__init__(url=url, width=width, height=height, timeout=timeout, *args, **kwargs)
 
 

platypush/message/event/web/widget.py

@@ -2,7 +2,16 @@ from platypush.message.event import Event
 
 
 class WidgetUpdateEvent(Event):
+    """
+    Event delivered to the dashboard when a widget update request is delivered to it
+    """
+
     def __init__(self, widget, *args, **kwargs):
+        """
+        :param widget: Widget ID
+        :type widget: str
+        """
+
         super().__init__(widget=widget, *args, **kwargs)