straighten out most parts after ruff

Author: VigneshVSV

docs/beginners-guide/articles/actions.md

@@ -7,7 +7,7 @@ Only methods decorated with `action()` are exposed to clients.
 ```py title="Actions" linenums="1" hl_lines="5 10 15 16 21 25"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:195:198"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:448:462"
---8<-- "docs/beginners-guide/code/thing_example_2.py:683:685"
+--8<-- "docs/beginners-guide/code/thing_example_2.py:682:685"
 --8<-- "docs/beginners-guide/code/thing_example_2.py:563:567"
 ```
 
@@ -403,7 +403,8 @@ 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`. 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`,
+they will run in a separate thread:
 
 ```py title="Threaded Actions" linenums="3"
 class ServoMotor(Thing):
@@ -426,6 +427,7 @@ The return value is fetched and returned to the client. One could also start lon
 class DCPowerSupply(Thing):
     """A DC Power Supply from 0-30V"""
 
+    # The suitability of this example in a realistic use case is untested
     @action(threaded=True)
     def monitor_over_voltage(self, period: float = 5):
         """background voltage monitor loop"""
@@ -440,16 +442,15 @@ class DCPowerSupply(Thing):
                     )
                 )
             time.sleep(period)
-    # The suitability of this example in a realistic use case is untested
 ```
 
-For `async` actions:
+For `async` actions, they are scheduled in the running event loop as a task:
 
 ```py title="Async Actions" linenums="3"
 class DCPowerSupply(Thing):
 
-    @action(create_task=True)
-    # @action(synchronous=False) # exactly the same effect for async methods
+    @action(synchronous=False)
+    # @action(create_task=True) # exactly the same effect for async methods
     async def monitor_over_voltage(self, period: float = 5):
         """background monitor loop"""
         while True:

docs/beginners-guide/articles/clients.md

@@ -10,6 +10,8 @@ Events are pushed to the client through a publish-subscribe mechanism through al
 
 ## Subscription
 
+[API Reference](../../api-reference/clients/object-proxy.md#hololinked.client.proxy.ObjectProxy.subscribe_event)
+
 One can subscribe to the event using the attribute name:
 
 === "threaded"
@@ -48,7 +50,9 @@ 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:
+---
+
+The callback function(s) must accept a single argument - 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):
@@ -57,7 +61,9 @@ def event_cb(event):
 
 > 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:
+---
+
+Each subscription creates a new event stream. One can also supply multiple callbacks which may be called in series or concurrently:
 
 === "sequential"
 
@@ -130,7 +136,7 @@ All subscriptions to the same event are removed.
 
 ## Payload Schema
 
-Schema may be supplied for the validation of the event data on the client using pydantic or JSON schema:
+Schema for the payload may be supplied using pydantic or JSON schema:
 
 ```py title="Payload Schema" linenums="1" hl_lines="13"
 class GentecMaestroEnergyMeter(Thing):
@@ -151,8 +157,6 @@ 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"

docs/beginners-guide/articles/events.md

@@ -1,6 +1,6 @@
 # Authentication Schemes
 
-Security schemes restrict access to the Thing instance, and are currently available only for HTTP.
+Security schemes are currently available only for HTTP.
 
 ### Basic Security Scheme
 
@@ -27,11 +27,14 @@ HTTP Basic authentication with username and password is supported with bcrypt an
 
     ```py title="Usage" linenums="1"
     import requests
+    from base64 import b64encode
     from requests.auth import HTTPBasicAuth
 
     response = requests.get(
-        "http://localhost:9000/properties/some_property",
-        auth=HTTPBasicAuth("admin", "adminpass")
+        "http://localhost:9000/secure-thing/some-property",
+        headers=dict(
+            Authorization=f"Basic {b64encode(b'someuser:somepassword').decode('utf-8')}"
+        ),
     )
     print(response.json())
     ```
@@ -43,7 +46,7 @@ HTTP Basic authentication with username and password is supported with bcrypt an
     from hololinked.client.security import HTTPBasicSecurityScheme
 
     client = ClientFactory.http(
-        "http://localhost:9000/my-thing/resources/wot-td",
+        url="http://localhost:9000/my-thing/resources/wot-td",
         security_scheme=HTTPBasicSecurityScheme(
             username="admin",
             password="adminpass",

docs/beginners-guide/articles/security.md

@@ -9,7 +9,7 @@ and large nested objects.
 Based on application requirements, it is possible to change the serialization format on an individual basis by using the `Serializers` singleton.
 Set the desired serialization on the specific property, action or event on the `Thing` subclass:
 
-```python
+```py linenums="1"
 from hololinked.serializers import Serializers
 
 # Using a pickle serializer for a list property
@@ -31,9 +31,9 @@ OceanOpticsSpectrometer(id="spectro1").run_with_http_server()
 
 Other properties, actions or events will still use the default JSON serialization.
 
-To overload the content type per thing instance:
+To overload the content type for an object per thing instance:
 
-```python
+```py linenums="1"
 from hololinked.serializers import Serializers
 
 spectrometer = OceanOpticsSpectrometer(id='spectro1')
@@ -56,7 +56,7 @@ spectrometer.run(...)
 
 To overload the default serializer for a `Thing` **instance**:
 
-```python
+```py linenums="1"
 from hololinked.serializers import Serializers
 
 spectrometer = OceanOpticsSpectrometer(id='spectro1')
@@ -77,7 +77,8 @@ Serializers.register_for_object_per_thing_instance(
 spectrometer.run(...)
 ```
 
-per-instance overloads have higher priority than the per-thing-object registrations.
+per-instance overloads have higher priority than the per-thing-object registrations. The singleton behaviour of `Serializers`
+ensures that all registrations are available across all protocol servers within the same process.
 
 ### Built-in Serializers
 
@@ -90,7 +91,7 @@ The following serializers are supported out of the box:
 
 ### Custom Serializers
 
-One can create custom serializers by subclassing the `BaseSerializer` class and implementing `dumps`, `loads`, and `content_type` methods.
+One can create custom serializers by subclassing the `BaseSerializer` and implementing `dumps`, `loads`, and `content_type` methods.
 Then, register the custom serializer for a specific property, action or event using the `Serializers` singleton as shown above.
 
 ```python

docs/beginners-guide/articles/serialization.md

@@ -1,11 +1,11 @@
 [API Reference](../../api-reference/state-machine/state-machine.md)
 
 Often, certain operations are not allowed during certain conditions, for example,
-one cannot turn ON a motor twice in a row, or a measurement device cannot modify a setting change if a measurement is ongoing.
+one cannot turn ON a motor twice in a row, or a measurement device cannot modify a setting if a measurement is ongoing.
 
 To implement these contraints, a state machine may be used to prevent property writes or
-action invokations in certain states (events are not supported). A `StateMachine` is a class-level
-attribute which accepts a finite list of states and the allowed properties and actions
+action invokations when a `Thing` is said to be in a certain state (events are not supported).
+A `StateMachine` is a class-level attribute which accepts a finite list of states and the allowed properties and actions
 in these states:
 
 ```py title="Definition" linenums="1"
@@ -60,8 +60,6 @@ def state_change_cb(event):
 client.observe_property(name="state", callbacks=state_change_cb)
 ```
 
-> One can supply multiple callbacks which may called in series or concurrently - see [Events](events.md#subscription).
-
 ## State Change Callbacks
 
 One can also supply callbacks which are executed when entering and exiting certain states,

docs/beginners-guide/articles/state-machine.md

@@ -20,7 +20,11 @@ thing = Thing(id="test-thing", logger=logger)
 thing.run_with_http_server(port=9000)
 ```
 
-<!-- #### Remote Access to Logger
+#### Remote Access to Logger
+
+To be updated after integration with opentelemetry & EFK stack. See [issues](https://github.com/hololinked-dev/hololinked/issues?q=is%3Aissue%20state%3Aopen%20milestone%3A%22logging%2C%20metrics%20and%20traces%22).
+
+<!--
 
 To stream the logs remotely, specify `remote_access_handler=True` while instantiating the `Thing`.
 
@@ -58,8 +62,10 @@ class MyThing(Thing):
         self.logger.info("Thing initialized with properties from DB")
 ```
 
-### Schema Validator
-
 ### Meta
 
+To be updated with use cases of modifying Thing metaclass.
+
 ### Composition
+
+To be updated with using sub-things within a Thing.

docs/beginners-guide/articles/thing/index.md

@@ -28,4 +28,4 @@ For good first issues, visit repository wise:
 - [website](https://github.com/hololinked-dev/website/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
 - [kubernetes](https://github.com/hololinked-dev/vps-kubernetes-cluster/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
 
-Our [contribution guidelines](https://github.com/hololinked-dev/hololinked/blob/main/CONTRIBUTING.md) may also help. There are also [weekly office hours](https://github.com/hololinked-dev#monthly-meetings) & [discord group](https://discord.com/invite/kEz87zqQXh) (currently no participants).
+Our [contribution guidelines](https://github.com/hololinked-dev/hololinked/blob/main/CONTRIBUTING.md) may also help, especially for new contributors & setting up development environments. There are also [weekly office hours](https://github.com/hololinked-dev#monthly-meetings) & [discord group](https://discord.com/invite/kEz87zqQXh) (currently no participants).