add event docs with latest info

VigneshVSV · VigneshVSV · commit 3ea19ee01f41 · 2025-08-31T10:29:53.000+02:00
diff --git a/docs/beginners-guide/articles/actions.md b/docs/beginners-guide/articles/actions.md
@@ -433,10 +433,10 @@ class DCPowerSupply(Thing):
     # The suitability of this example in a realistic use case is untested
 ```
 
-For long running actions that do not return, call them with `noblock` flag on the client, otherwise except a `TimeoutError`:
+For long running actions that do not return, call them with `oneway` flag on the client, otherwise except a `TimeoutError`:
 
 ```py
-client.invoke_action("monitor_over_voltage", period=10, noblock=True)
+client.invoke_action("monitor_over_voltage", period=10, oneway=True)
 ```
 
 ## Thing Description Metadata
diff --git a/docs/beginners-guide/articles/events.md b/docs/beginners-guide/articles/events.md
@@ -1,62 +1,180 @@
-Events
-======
+# Events
 
-[API Reference](../../../api-reference/events/index.md)
+[API Reference](../../api-reference/events/index.md)
 
-Events are pushed to the client through a publish-subscribe mechanism. Call ``push()`` method on the event to 
-publish data to clients:
+Events are pushed to the client through a publish-subscribe mechanism through all the protocols. Call `push()` method on the event to publish data to clients:
 
-```py title="Definition" linenums="1" hl_lines="17-21"
---8<-- "docs/howto/code/events/definition.py:5:25"
+```py title="Definition" linenums="1" hl_lines="21-23"
+--8<-- "docs/beginners-guide/code/events/definition.py:3:25"
 ```
 
+## Subscription
+
 One can subscribe to the event using the attribute name:
 
-```py title="Subscription" linenums="1" hl_lines="9-10"
---8<-- "docs/howto/code/events/event_client.py:1:10"
-```
-    
+=== "threaded"
+
+    In the default synchronous mode, the `subscribe_event` method spawns a thread that listens to the event in backgound:
+
+    ```py title="Subscription" linenums="1" hl_lines="9"
+    from hololinked.client import ClientFactory
+
+    energy_meter = ClientFactory.http(url="http://localhost:8000/energy-meter")
+    # energy_meter = ClientFactory.zmq(id="energy_meter", access_point="IPC")
+
+    def event_cb(event_data):
+        print(event_data)
 
-One can also supply multiple callbacks which may called in series or threaded:
+    energy_meter.subscribe_event(name="data_point_event", callbacks=event_cb)
+    ```
+
+=== "async"
+
+    In the asynchronous mode, the `subscribe_event` method creates an event listening task in the running async loop:
 
-=== "Sequential"
+    ```py title="Subscription" linenums="1" hl_lines="9"
+    from hololinked.client import ClientFactory
 
-    ```py title="Providing Callbacks" linenums="1" hl_lines="9"
-    --8<-- "docs/howto/code/events/event_client.py:13:22"
+    energy_meter = ClientFactory.http(url="http://localhost:8000/energy-meter")
+    # energy_meter = ClientFactory.zmq(id="energy_meter", access_point="IPC")
+
+    def event_cb(event_data):
+        print(event_data)
+
+    energy_meter.subscribe_event(
+        name="data_point_event",
+        callbacks=event_cb,
+        asynch=True
+    )
     ```
 
-=== "Threaded"
+---
+
+One can also supply multiple callbacks which may called in series, threaded or async:
+
+=== "sequential"
+
+    The background thread that listens to the event executes the callbacks in series in its own thread:
+
+    ```py title="Sequential Callbacks" linenums="1" hl_lines="9"
+    def event_cb1(event_data):
+        print("First Callback", event_data)
+
+    def event_cb2(event_data):
+        print("Second callback", event_data)
+
+    energy_meter.subscribe_event(
+        name="statistics_event",
+        callbacks=[event_cb1, event_cb2]
+    )
+    ```
+
+    So please be careful while using GUI frameworks like PyQt where you can paint the GUI only from the main thread.
+    You would need to use signals and slots or other mechanisms.
+
+=== "threaded"
+
+    The background thread that listens to the event executes the callbacks by spawning new threads:
+
+    ```py title="Thread Callbacks" linenums="1" hl_lines="9-10"
+    def event_cb1(event_data):
+        print("First Callback", event_data)
+
+    def event_cb2(event_data):
+        print("Second callback", event_data)
 
-    ```py title="Providing Callbacks" linenums="1" hl_lines="9-10"
-    --8<-- "docs/howto/code/events/event_client.py:13:18"
-    --8<-- "docs/howto/code/events/event_client.py:24:"
+    energy_meter.subscribe_event(
+        name="statistics_event",
+        callbacks=[event_cb1, event_cb2],
+        thread_callbacks=True
+    )
     ```
+    Again, please be careful while using GUI frameworks like PyQt where you can paint the GUI only from the main thread.
+
+=== "async"
+
+    Applies only when listening to event with `async=True`, the `async` method creates new tasks in the current loop:
+
+    ```py title="Thread Callbacks" linenums="1"
+    async def event_cb1(event_data):
+        print("First Callback", event_data)
+        await some_async_function1(event_data)
+
+    async def event_cb2(event_data):
+        print("Second callback", event_data)
+        await some_async_function2(event_data)
+
+    energy_meter.subscribe_event(
+        name="statistics_event",
+        callbacks=[event_cb1, event_cb2],
+        asynch=True,
+        create_task_for_cbs=True
+    )
+    ```
+
+---
+
+To unsubscribe:
+
+```py title="Unsubscription" linenums="1"
+energy_meter.unsubscribe_event(name="data_point_event")
+```
+
+## Payload Schema
 
 Schema may be supplied for the validation of the event data on the client:
 
 ```py title="" linenums="1" hl_lines="13"
---8<-- "docs/howto/code/events/definition.py:6:6"
---8<-- "docs/howto/code/events/definition.py:50:62"
-``` 
-    
-There is no separate validation on the server side. 
-
-
-<!-- .. list-table:: Thing Description for Events
-   :header-rows: 1
-
-   * - Key
-     - Supported
-     - Comment
-   * - subscription
-     - ✖
-     -
-   * - data
-     - ✔
-     - payload schema for the event
-   * - dataResponse
-     - ✖
-     - schema for response message after arrival of an event, will be supported in future
-   * - cancellation
-     - ✖
-     - Server sent events can be cancelled by the client directly  -->
+class GentecMaestroEnergyMeter(Thing):
+
+    data_point_event_schema = {
+        "type": "object",
+        "properties": {
+            "timestamp": {"type": "string", "format": "date-time"},
+            "energy": {"type": "number"}
+        },
+        "required": ["timestamp", "energy"],
+    }
+
+    data_point_event = Event(
+        doc="Event raised when a new data point is available",
+        label="Data Point Event",
+        schema=data_point_event_schema,
+    )
+```
+
+There is no separate validation on the server side.
+
+???+ "Schema as seen in Thing Description"
+
+    ```py
+    GentecMaestro.data_point_event.to_affordance().json()
+    ```
+
+    ```json
+    {
+        "description": "Event raised when a new data point is available",
+        "data": {
+            "type": "object",
+            "properties": {
+                "timestamp": {
+                    "type": "string",
+                    "format": "date-time"
+                },
+                "energy": {
+                    "type": "number"
+                }
+            },
+            "required": ["timestamp", "energy"]
+        }
+    }
+    ```
+
+## Thing Description Metadata
+
+| Key          | Supported | Comment                                                                            |
+| ------------ | --------- | ---------------------------------------------------------------------------------- |
+| subscription | ✖         |                                                                                    |
+| data         | ✔         | payload schema for the event                                                       |
+| dataResponse | ✖         | schema for response message after arrival of an event, will be supported in future |
+| cancellation | -         | Server sent events can be cancelled by the client directly                         |
diff --git a/docs/beginners-guide/code/events/definition.py b/docs/beginners-guide/code/events/definition.py
@@ -1,69 +1,66 @@
-import datetime, threading
-from hololinked.server import Thing, Event, Property
-import json
+import datetime
+import threading
+from hololinked.core import Thing, Event, Property
 
 
 class GentecMaestroEnergyMeter(Thing):
     """
     Simple example to implement acquisition loops and events
-    to push the captured data. Customize it for your application or 
+    to push the captured data. Customize it for your application or
     implement your own.
     """
 
-    data_point_event = Event(friendly_name='data-point-event', 
-                            doc='Event raised when a new data point is available',
-                            label='Data Point Event')
-    
+    data_point_event = Event(
+        doc="Event raised when a new data point is available",
+        label="Data Point Event",
+    )
+
     def loop(self):
         self._run = True
         while self._run:
-            self._last_measurement = self.current_value
+            self._last_measurement = self.read_current_value()
             timestamp = datetime.datetime.now().strftime("%H:%M:%S")
-            self.data_point_event.push(dict(
-                    timestamp=timestamp, 
-                    energy=self._last_measurement
-                ))
+            self.data_point_event.push(
+                dict(timestamp=timestamp, energy=self._last_measurement)
+            )
             if self._statistics_enabled:
                 self.statistics_event.push(self.statistics)
-    
-    statistics_event = Event(friendly_name='statistics-event',
-                            doc='Event raised when a new statistics is available',
-                            label='Statistics Event')
 
+    statistics_event = Event(
+        friendly_name="statistics-event",
+        doc="Event raised when a new statistics is available",
+        label="Statistics Event",
+    )
 
-    statistics = Property(doc="Get latest computed statistics", 
-                        readonly=True)
+    statistics = Property(doc="Get latest computed statistics", readonly=True)
 
     @statistics.getter
     def get_statistics(self):
         """get latest computed statistics"""
         raw_data = self.serial_comm_handle.execute_instruction("*VSU\r\n", 1000)
         if raw_data is not None:
-            data = raw_data.split('\t')
+            data = raw_data.split("\t")
             ret = {}
             for qty in data:
-                name, value = qty.split(':')
+                name, value = qty.split(":")
                 ret[name] = float(value)
             return ret
         raise RuntimeError("Could not get statistics")
-    
-   
+
     data_point_event_schema = {
         "type": "object",
-        "properties": {
-            "timestamp": {"type": "string"},
-            "energy": {"type": "number"}
-        },
-        "required": ["timestamp", "energy"]
+        "properties": {"timestamp": {"type": "string"}, "energy": {"type": "number"}},
+        "required": ["timestamp", "energy"],
     }
 
-    data_point_event = Event(doc='Event raised when a new data point is available',
-                            label='Data Point Event', schema=data_point_event_schema)
-  
-    
+    data_point_event = Event(
+        doc="Event raised when a new data point is available",
+        label="Data Point Event",
+        schema=data_point_event_schema,
+    )
+
+
 if __name__ == "__main__":
     threading.Thread(target=start_https_server).start()
     # add your HTTP server starter code in the above method
-    GentecMaestroEnergyMeter(
-        instance_name='gentec-maestro'
-    ).run(zmq_protocols='IPC')
+    GentecMaestroEnergyMeter(instance_name="gentec-maestro").run(zmq_protocols="IPC")
diff --git a/docs/beginners-guide/code/events/event_client.py b/docs/beginners-guide/code/events/event_client.py
@@ -1,28 +1,26 @@
-from hololinked.client import ObjectProxy
+from hololinked.client import ClientFactory
+
+energy_meter = ClientFactory.http(url="http://localhost:8000/energy-meter")
+# energy_meter = ClientFactory.zmq(id="energy_meter", access_point="IPC")
 
-# events works also through inter-process communication, apart from TCP
-energy_meter_proxy = ObjectProxy(instance_name='gentec-maestro', protocol='IPC') 
 
 def event_cb(event_data):
     print(event_data)
 
-energy_meter_proxy.subscribe_event(name='data_point_event', 
-                                callbacks=event_cb)
+
+energy_meter.subscribe_event(name="data_point_event", callbacks=event_cb)
 
 
 def event_cb1(event_data):
     print(event_data)
 
+
 def event_cb2(event_data):
     print("Second callback", event_data)
 
-energy_meter_proxy.subscribe_event(
-                                name='statistics_event', 
-                                callbacks=[event_cb1, event_cb2]         
-                            )
 
-energy_meter_proxy.subscribe_event(
-                                name='statistics_event', 
-                                callbacks=[event_cb1, event_cb2], 
-                                thread_callbacks=True
-                            )
+energy_meter.subscribe_event(name="statistics_event", callbacks=[event_cb1, event_cb2])
+
+energy_meter.subscribe_event(
+    name="statistics_event", callbacks=[event_cb1, event_cb2], thread_callbacks=True
+)
