Added documentation to eventhandler and smartobject

eventhandler.py

@@ -1,6 +1,53 @@
 import appdaemon.plugins.hass.hassapi as hass
-import pickle
-import os
+
+# =============================================================================
+# EventDispatcher / EventHandler — HA event subscription helpers
+# =============================================================================
+#
+# EventDispatcher
+# ---------------
+# Subscribes to a single HA event and invokes a callback when the event fires
+# and its payload matches the configured filter.
+#
+#   event_name   : HA event name to listen for.
+#   event_data   : dict of key/value pairs that must all match the event
+#                  payload (deep partial match — nested dicts are matched
+#                  recursively).  None means "match any payload".
+#   reset_data   : optional dict.  When set, the dispatcher becomes a
+#                  one-shot latch: the callback fires once on event_data
+#                  match, then waits for a reset_data match before it can
+#                  fire again.  Useful for press/release pairs.
+#   event_context: arbitrary value forwarded as the third argument to the
+#                  callback — use it to identify which dispatcher fired.
+#
+# Callback signature: callback(event_name, event_data, event_context)
+#
+# EventHandler
+# ------------
+# Convenience wrapper that creates one EventDispatcher per entry in an
+# events_block dict (the YAML "events_to_listen" structure).
+#
+# YAML events_block format:
+#   events_to_listen:
+#     <key>:
+#       event_name: <ha_event_name>         # required
+#       event_data:                         # optional — payload filter
+#         <field>: <value>
+#       reset_data:                         # optional — latch reset filter
+#         <field>: <value>
+#
+# Usage:
+#   handler = EventHandler(ad_api, self.args['events_to_listen'], my_callback)
+#   # Keep a reference to handler — it owns the subscriptions.
+#
+# Or construct the events_block programmatically:
+#   handler = EventHandler(
+#       ad_api,
+#       {'evt': {'event_name': 'MY_EVENT', 'event_data': {'key': 'value'}}},
+#       my_callback,
+#       event_context='optional_context'
+#   )
+# =============================================================================
 
 class EventDispatcher:
     def __init__(self,ad_api,event_name,callback,event_data,reset_data,event_context):
@@ -69,11 +116,8 @@ class EventHandler:
         self.__ad_api = ad_api
         self.event_dispatchers = []
 
-        #try: 
         for event_block in events_block.values():
             register_event_with_params(event_block,callback,event_context)
-        #except (AttributeError):
-        #    self.log(f"Format not supported : {events_block}")
 
     def log(self,message,**kwargs):
         self.__ad_api.log(message,**kwargs)
@@ -81,19 +125,4 @@ class EventHandler:
     def add_dispatcher(self,event_name,callback,event_data = None,reset_data = None ,event_context = None):
         self.log(f'Registering dispatcher {callback.__name__} for event "{event_name}" ({event_data})')
         dispatcher = EventDispatcher(self.__ad_api,event_name,callback,event_data,reset_data,event_context)
-        self.event_dispatchers.append(dispatcher)
-
-        # if not event_name in self.event_dispatchers:
-        #     self.event_dispatchers[event_name] = list()
-        #     self.log(f"listening event {event_name}")
-        #     self.__ad_api.listen_event(self._on_event_internal,event_name)
-
-        # self.event_dispatchers[event_name].append(dispatcher)
-
-    # def _on_event_internal(self, event_name, data, kwargs):
-    #     if event_name in self.event_dispatchers:
-    #         for dispatcher in self.event_dispatchers[event_name]:
-    #             if dispatcher.process_event(data) == True:
-    #                 break
-    #     else:
-    #         self.log(f"{event_name} has no dispatcher registered",level="WARNING")
+        self.event_dispatchers.append(dispatcher)