re-read and optimize

Author: VigneshVSV

.vscode/settings.json

@@ -2,5 +2,5 @@
     "editor.rulers": [
         80,120
     ],
-    "editor.formatOnSave": true,
+    "editor.formatOnSave": true
 }

docs/beginners-guide/articles/actions.md

@@ -4,7 +4,7 @@
 
 Only methods decorated with `action()` are exposed to clients.
 
-```py title="Actions" linenums="1"
+```py title="Actions" linenums="1" hl_lines="5 10 15 16 21 25"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:189:192"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:431:445"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:643:646"
@@ -13,17 +13,16 @@ Only methods decorated with `action()` are exposed to clients.
 
 ## Payload Validation
 
-Arguments are loosely typed and may need to be constrained with a schema based
-on the robustness the developer is expecting in their application:
+If arguments are loosely typed, the action will be invoked with given payload without any validation. One may validate them manually inside the method. However, one can also specify the expected argument schema using either `JSON Schema` or `pydantic` models:
 
 <a id="actions-argument-schema"></a>
 === "JSON Schema"
 
     === "Single Argument"
 
-        Just specify the expected type of the argument (with or without name)
+        Specify the expected type of the argument (with or without name)
 
-        ```py title="Input Schema" linenums="1"
+        ```py title="Input Schema" linenums="1" hl_lines="8"
         --8<-- "docs/beginners-guide/code/thing_example_2.py:189:192"
         --8<-- "docs/beginners-guide/code/thing_example_2.py:210:222"
         ```
@@ -47,10 +46,10 @@ on the robustness the developer is expecting in their application:
 
     === "Multiple Arguments"
 
-        You need to specify the action argument names under the `properties` field with `type` as `object`.
-        Names not found in the `properties` field can be subsumed under python spread operator `**kwargs` if necessary.
+        Specify the argument names under the `properties` field with `type` as `object`.
+        Names not found in the `properties` field can be subsumed under python spread operator `**kwargs` if necessary (dont set `additionalProperties` to `False` in that case).
 
-        ```py title="Input Schema with Multiple Arguments" linenums="1"
+        ```py title="Input Schema with Multiple Arguments" linenums="1" hl_lines="32"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:57:85"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:87:87"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:213:226"
@@ -99,7 +98,9 @@ on the robustness the developer is expecting in their application:
 
     === "Return Type"
 
-        ```py title="With Return Type"
+        Specify return type under `output_schema` field:
+
+        ```py title="With Return Type" linenums="1" hl_lines="38 39"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:22:55"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:87:87"
         --8<-- "docs/beginners-guide/code/thing_example_3.py:349:356"
@@ -151,7 +152,9 @@ on the robustness the developer is expecting in their application:
 
     === "Single Argument"
 
-        ```py title="Input Schema with Single Argument" linenums="1"
+        Type annotate the argument, either plainly or with `Annotated`. A pydantic model will be composed with the argument name as the field name and the type annotation as the field type:
+
+        ```py title="Input Schema with Single Argument" linenums="1" hl_lines="7"
         from typing import Annotated
 
         class GentecOpticalEnergyMeter(Thing):
@@ -196,6 +199,8 @@ on the robustness the developer is expecting in their application:
 
     === "Multiple Arguments"
 
+        Again, type annotate the arguments, either plainly or with `Annotated`:
+
         ```py title="Input Schema with Multiple Arguments"
         from typing import Literal
 
@@ -284,6 +289,8 @@ on the robustness the developer is expecting in their application:
 
     === "Return Type"
 
+        type annotate the return type:
+
         ```py
         from typing import Annotated
         from pydantic import Field
@@ -321,8 +328,38 @@ on the robustness the developer is expecting in their application:
             }
             ```
 
-However, a schema is optional and it only matters that
-the method signature is matching when requested from a client.
+    === "Supply Models Directly"
+
+        If the composed models from the type annotations are not sufficient or contain errors, one may directly supply the models:
+
+        ```py title="With Direct Models" linenums="1" hl_lines="3 7 22"
+        from pydantic import BaseModel, field_validator
+
+        class CommandModel(BaseModel):
+            command: str
+            return_data_size: int = Field(0, ge=0)
+
+            @field_validator("command")
+            def validate_command(cls, v):
+                if not isinstance(v, str) or not v:
+                    raise ValueError("Command must be a non-empty string")
+                if command not in SerialUtility.supported_commands:
+                    raise ValueError(f"Command {command} is not supported")
+                return v
+
+        class ResponseModel(BaseModel):
+            response: str = Field(..., description="Response from the device")
+
+        class SerialUtility(Thing):
+
+            supported_commands = ["*IDN?", "MEAS:VOLT?", "MEAS:CURR?"]
+
+            @action(input_schema=CommandModel, output_schema=ResponseModel)
+            def execute_instruction(self, command: str, return_data_size: int = 0) -> str:
+                """
+                executes instruction given by the ASCII string parameter 'command'
+                """
+        ```
 
 <!-- To enable this, set global attribute`allow_relaxed_schema_actions=True`. This setting is used especially when a schema is useful for validation of arguments but not available - not for methods with no arguments.
 
@@ -366,8 +403,7 @@ client side, there is no difference between invoking a normal action and an acti
 
 ## Threaded & Async Actions
 
-Actions can be made asynchronous or threaded by setting the `synchronous` flag to `False` in the decorator. For methods
-that are **not** `async`:
+Actions can be made asynchronous or threaded by setting the `synchronous` flag to `False`. For methods that are **not** `async`:
 
 ```py title="Threaded Actions" linenums="3"
 class ServoMotor(Thing):
@@ -408,32 +444,32 @@ class DCPowerSupply(Thing):
     # The suitability of this example in a realistic use case is untested
 ```
 
-Same applies for `async`:
+For `async` actions:
 
 ```py title="Async Actions" linenums="3"
 class DCPowerSupply(Thing):
 
     @action(create_task=True)
+    # @action(synchronous=False) # exactly the same effect for async methods
     async def monitor_over_voltage(self, period: float = 5):
         """background monitor loop"""
         while True:
             voltage = await asyncio.get_running_loop().run_in_executor(
                             None, self.measure_voltage
                     )
             if voltage > self.over_voltage_threshold:
+                timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
                 self.over_voltage_event(
                     dict(
-                        timestamp=datetime.datetime.now().strftime(
-                            "%Y-%m-%d %H:%M:%S"
-                        ),
+                        timestamp=timestamp,
                         voltage=voltage
                     )
                 )
             await asyncio.sleep(period)
     # The suitability of this example in a realistic use case is untested
 ```
 
-For long running actions that do not return, call them with `oneway` 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 expect a `TimeoutError`:
 
 ```py
 client.invoke_action("monitor_over_voltage", period=10, oneway=True)

docs/beginners-guide/articles/events.md

@@ -30,16 +30,16 @@ One can subscribe to the event using the attribute name:
 
 === "async"
 
-    In the asynchronous mode, the `subscribe_event` method creates an event listening task in the running async loop:
+    In the asynchronous mode, the `subscribe_event` method creates an event listening task in the running async loop. This requires the client to be running in an async loop, otherwise no events will be received although the server will be publishing it:
 
     ```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)
+    def event_cb(event):
+        print(event)
 
     energy_meter.subscribe_event(
         name="data_point_event",
@@ -48,70 +48,76 @@ One can subscribe to the event using the attribute name:
     )
     ```
 
----
+The callback function(s) must accept a single argument which is the event data payload, an instance of `SSE` object. The payload can be accessed as using the `data` attribute:
+
+```py title="Event Data" linenums="1" hl_lines="9"
+def event_cb(event):
+    print(event.data)
+```
 
-One can also supply multiple callbacks which may called in series, threaded or async:
+> The `SSE` object also contains metadata like `id`, `event` name and `retry` interval, but these are currently not well supported. Improvements in the future are expected.
+
+Each subscription creates a new event stream. One can also supply multiple callbacks which may called in series or concurrently:
 
 === "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_cb1(event):
+        print("First Callback", event.data)
 
-    def event_cb2(event_data):
-        print("Second callback", event_data)
+    def event_cb2(event):
+        print("Second callback", event.data)
 
     energy_meter.subscribe_event(
         name="statistics_event",
         callbacks=[event_cb1, event_cb2]
+        # This also works for async where all callbacks are awaited in series
     )
     ```
 
-    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_cb1(event):
+        print("First Callback", event.data)
 
-    def event_cb2(event_data):
-        print("Second callback", event_data)
+    def event_cb2(event):
+        print("Second callback", event.data)
 
     energy_meter.subscribe_event(
         name="statistics_event",
         callbacks=[event_cb1, event_cb2],
-        thread_callbacks=True
+        concurrent=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:
+    The event listening task creates newer tasks in the running event loop:
 
-    ```py title="Thread Callbacks" linenums="1"
-    async def event_cb1(event_data):
-        print("First Callback", event_data)
-        await some_async_function1(event_data)
+    ```py title="Thread Callbacks" linenums="1" hl_lines="12-13"
+    async def event_cb1(event):
+        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)
+    async def event_cb2(event):
+        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
+        concurrent=True
     )
     ```
 
+> In GUI frameworks like PyQt, you cannot paint the GUI from the event thread. You would need to use signals and slots or other mechanisms to update the GUI to hand over the data.
+
 ---
 
 To unsubscribe:
@@ -120,11 +126,13 @@ To unsubscribe:
 energy_meter.unsubscribe_event(name="data_point_event")
 ```
 
+All subscriptions to the same event are removed.
+
 ## Payload Schema
 
-Schema may be supplied for the validation of the event data on the client:
+Schema may be supplied for the validation of the event data on the client using pydantic or JSON schema:
 
-```py title="" linenums="1" hl_lines="13"
+```py title="Payload Schema" linenums="1" hl_lines="13"
 class GentecMaestroEnergyMeter(Thing):
 
     data_point_event_schema = {
@@ -145,6 +153,8 @@ class GentecMaestroEnergyMeter(Thing):
 
 There is no separate validation on the server side.
 
+> There is no validation on the client side currently implemented in `hololinked.client`. This will be added in future releases.
+
 ???+ "Schema as seen in Thing Description"
 
     ```py
@@ -172,9 +182,9 @@ There is no separate validation on the server side.
 
 ## 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                         |
+| Key          | Supported | Comment                                                    |
+| ------------ | --------- | ---------------------------------------------------------- |
+| subscription | ✖         |                                                            |
+| data         | ✔         | payload schema for the event                               |
+| dataResponse | ✖         | will be supported in a future release                      |
+| cancellation | -         | Server sent events can be cancelled by the client directly |