Added documentation to events

This commit is contained in:
Fabio Manganiello 2018-07-09 22:37:54 +02:00
parent 0288f7ee1b
commit b94ec36d0f
41 changed files with 554 additions and 19 deletions

28
docs/source/events.rst Normal file
View file

@ -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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -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:

View file

@ -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)

View file

@ -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)

View file

@ -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)

View file

@ -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,

View file

@ -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)

View file

@ -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:

View file

@ -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)

View file

@ -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)

View file

@ -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)

View file

@ -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:

View file

@ -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:

View file

@ -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)

View file

@ -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)

View file

@ -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)

View file

@ -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:

View file

@ -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)

View file

@ -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)

View file

@ -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)