fixed some issues and added some docs

Author: jryannel

README.md

@@ -1,21 +1,37 @@
 # ObjectLink Core Protocol in Python
 
-The ObjectLink protocol is designed to link a local object with a remote objec over a websocket connection.
+The ObjectLink protocol is designed to link a local object with a remote object over a websocket connection.
 
-It supports distributed properties, asynchronous method invokation as also server side signals.
+It supports distributed properties, asynchronous method invocation as also server side signals.
 
 It is designed to wort together with ApiGear Object Model to generate complete client and server side APIs.
 
-# Install for testing
+# Setup for testing
 
 This will install the package as editable python package, which can be used for local development.
 
 ```
 pip install -e .
 ```
 
-# Publish package
+# Testing
 
-TBD
+```
+pip install pytest
+pytest
+```
+
+# Running the server
 
+The server is a starlette server (https://www.starlette.io) which can be installed with
 
+```
+pip3 install starlette
+pip3 install uvicorn
+```
+
+and run using
+
+```
+uvicorn demo:app --port=8080
+```

server.py renamed to demo_server.py

@@ -13,40 +13,48 @@
 class Counter:
     count = 0
     _node: RemoteNode
+
     def increment(self):
         self.count += 1
-        self._node.notify_property_change('demo.Counter/count', self.count)
+        # notify all registered clients
+        RemoteNode.notify_property_change('demo.Counter/count', self.count)
+
 
 class CounterAdapter(IObjectSource):
     node: RemoteNode = None
+
     def __init__(self, impl):
         self.impl = impl
-        RemoteNode.add_object_source(self)
+        # need to register this source with the registry
+        RemoteNode.register_source(self)
 
     def olink_object_name(self):
+        # name this source is registered under
         return 'demo.Counter'
 
     def olink_invoke(self, name: str, args: list[Any]) -> Any:
+        # called on incoming invoke message
         path = Name.path_from_name(name)
         func = getattr(self.impl, path)
         func()
 
     def olink_set_property(self, name: str, value: Any):
+        # called on incoming set property message
         path = Name.path_from_name(name)
         setattr(self, self.impl, value)
 
     def olink_linked(self, name: str, node: "RemoteNode"):
+        # called when a remote node is linked to this node
         self.impl._node = node
 
     def olink_collect_properties(self) -> object:
         return {k: getattr(self.impl, k) for k in ['count']}
 
+
 counter = Counter()
 adapter = CounterAdapter(counter)
 
 
-
-
 class RemoteEndpoint(WebSocketEndpoint):
     encoding = "text"
     node = RemoteNode()
@@ -59,7 +67,7 @@ async def sender(self, ws):
             msg = await self.queue.get()
             print('send', msg)
             await ws.send_text(msg)
-            self.queue.task_done()        
+            self.queue.task_done()
 
     async def on_connect(self, ws: WebSocket):
         print('on_connect')
@@ -71,7 +79,6 @@ def writer(msg: str):
         self.node.on_write(writer)
         await super().on_connect(ws)
 
-
     async def on_receive(self, ws: WebSocket, data: Any) -> None:
         print('on_receive', data)
         self.node.handle_message(data)
@@ -82,9 +89,8 @@ async def on_disconnect(self, websocket: WebSocket, close_code: int) -> None:
         await self.queue.join()
 
 
-
 routes = [
     WebSocketRoute("/ws", RemoteEndpoint)
 ]
 
-app = Starlette(routes=routes)
+app = Starlette(routes=routes)

src/olink/clientnode.py

@@ -12,9 +12,12 @@ def __init__(self, name: str, value: Any):
     name: str
     value: Any
 
+
 InvokeReplyFunc = Callable[[InvokeReplyArg], None]
 
+
 class IObjectSink(ProtocolType):
+    # interface for object sinks
     def olink_object_name() -> str:
         # return object name
         raise NotImplementedError()
@@ -35,9 +38,12 @@ def olink_on_release(self) -> None:
         # called when sink is released
         raise NotImplementedError()
 
+
 class SinkToClientEntry:
+    # entry in the client registry
     sink: IObjectSink = None
     node: "ClientNode" = None
+
     def __init__(self, sink=None):
         self.sink = sink
         self.node = None
@@ -53,7 +59,7 @@ def remove_node(self, node: "ClientNode"):
             if entry.node is node:
                 entry.node = None
 
-    def add_node_to_sink(self, name: str, node: "ClientNode"):        
+    def add_node_to_sink(self, name: str, node: "ClientNode"):
         # add not to named sink
         self._entry(name).node = node
 
@@ -64,7 +70,8 @@ def remove_node_from_sink(self, name: str, node: "ClientNode"):
             if self.entries[resource].node is node:
                 self.entries[resource].node = None
             else:
-                self.emit_log(LogLevel.DEBUG, f"unlink node failed, not the same node: {resource}")
+                self.emit_log(
+                    LogLevel.DEBUG, f"unlink node failed, not the same node: {resource}")
 
     def register_sink(self, sink: IObjectSink) -> "ClientNode":
         # register sink using object name
@@ -77,7 +84,7 @@ def unregister_sink(self, sink: IObjectSink):
         # unregister sink using object name
         name = sink.olink_object_name()
         self._remove_entry(name)
-        
+
     def get_sink(self, name: str) -> Optional[IObjectSink]:
         # get sink using name
         return self._entry(name).sink
@@ -103,10 +110,14 @@ def _remove_entry(self, name: str) -> None:
 # global client registry
 _registry = ClientRegistry()
 
+
 def get_client_registry() -> ClientRegistry:
+    # get global client registry
     return _registry
 
+
 class ClientNode(BaseNode):
+    # client side node
     invokes_pending: dict[int, InvokeReplyFunc] = {}
     requestId = 0
 
@@ -121,15 +132,17 @@ def next_request_id(self) -> int:
         return self.requestId
 
     def invoke_remote(self, name: str, args: list[Any], func: Optional[InvokeReplyFunc]) -> None:
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.invoke_remote: {name} {args}")
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.invoke_remote: {name} {args}")
         request_id = self.next_request_id()
         if func:
             self.invokes_pending[request_id] = func
         self.emit_write(Protocol.invoke_message(request_id, name, args))
 
     def set_remote_property(self, name: str, value: Any) -> None:
         # send remote propertymessage
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.set_remote_property: {name} {value}")   
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.set_remote_property: {name} {value}")
         self.emit_write(Protocol.set_property_message(name, value))
 
     def link_node(self, name: str):
@@ -144,18 +157,19 @@ def unlink_node(self, name: str) -> None:
     def register_sink(sink: IObjectSink) -> Optional["ClientNode"]:
         # register sink to registry
         return get_client_registry().register_sink(sink)
-    
+
     @staticmethod
     def unregister_sink(sink: IObjectSink) -> None:
         # unregister sink from registry
         return get_client_registry().unregister_sink(sink)
 
     @staticmethod
     def get_sink(name: str) -> Optional[IObjectSink]:
+        # get sink from registry
         return get_client_registry().get_sink(name)
 
-    def link_remote(self, name: str):      
-        # register this node from sink and send a link message  
+    def link_remote(self, name: str):
+        # register this node from sink and send a link message
         self.emit_log(LogLevel.DEBUG, f"ClientNode.linkRemote: {name}")
         self.registry().add_node_to_sink(name, self)
         self.emit_write(Protocol.link_message(name))
@@ -175,14 +189,16 @@ def handle_init(self, name: str, props: object):
 
     def handle_property_change(self, name: str, value: Any) -> None:
         # handle property change message from source
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.handle_property_change: {name}")
-        sink =self.get_sink(name)
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.handle_property_change: {name}")
+        sink = self.get_sink(name)
         if sink:
             sink.olink_on_property_changed(name, value)
 
     def handle_invoke_reply(self, id: int, name: str, value: Any) -> None:
         # handle invoke reply message from source
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.handle_invoke_reply: {id} {name} {value}")
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.handle_invoke_reply: {id} {name} {value}")
         if id in self.invokes_pending:
             func = self.invokes_pending[id]
             if func:
@@ -194,14 +210,13 @@ def handle_invoke_reply(self, id: int, name: str, value: Any) -> None:
 
     def handle_signal(self, name: str, args: list[Any]) -> None:
         # handle signal message from source
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.handle_signal: {name} {args}")
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.handle_signal: {name} {args}")
         sink = self.get_sink(name)
         if sink:
             sink.olink_on_signal(name, args)
 
     def handle_error(self, msgType: MsgType, id: int, error: str):
         # handle error message from source
-        self.emit_log(LogLevel.DEBUG, f"ClientNode.handle_error: {msgType} {id} {error}")
-
-
-    
+        self.emit_log(LogLevel.DEBUG,
+                      f"ClientNode.handle_error: {msgType} {id} {error}")

src/olink/core/node.py

@@ -4,24 +4,29 @@
 
 
 class BaseNode(Base, IProtocolListener):
+    # base node class
     write_func: WriteMessageFunc = None
-    converter: MessageConverter =  None
+    converter: MessageConverter = None
     protocol: Protocol = None
+
     def __init__(self):
         super()
         self.protocol = Protocol(self)
         self.converter = MessageConverter(MessageFormat.JSON)
-    
+
     def on_write(self, func: WriteMessageFunc) -> None:
+        # set the write function
         self.write_func = func
 
     def emit_write(self, msg: list[Any]) -> None:
+        # emit a message using the write function
         if self.write_func:
             data = self.converter.to_string(msg)
             self.write_func(data)
         else:
             self.emit_log(LogLevel.DEBUG, f"write not set on protocol: {msg}")
 
     def handle_message(self, data: str) -> None:
+        # handle a message and pass is on to the protocol
         msg = self.converter.from_string(data)
         self.protocol.handle_message(msg)

src/olink/core/protocol.py

@@ -2,40 +2,53 @@
 from typing import Protocol as ProptocolType
 from .types import Base, LogLevel, MsgType
 
+
 class IProtocolListener(ProptocolType):
+    # interface for protocol listeners
     def handle_link(self, name: str) -> None:
+        # called when a link is created
         raise NotImplementedError()
 
     def handle_unlink(self, name: str) -> None:
+        # called when a link is released
         raise NotImplementedError()
 
     def handle_init(self, name: str, props: object) -> None:
+        # called when a node is initialized
         raise NotImplementedError()
 
     def handle_set_property(self, name: str, value: Any) -> None:
+        # called when a property is set
         raise NotImplementedError()
 
     def handle_property_change(self, name: str, value: Any) -> None:
+        # called when a property is changed
         raise NotImplementedError()
 
     def handle_invoke(self, id: int, name: str, args: list[Any]) -> None:
+        # called when a node invokes a method
         raise NotImplementedError()
 
     def handle_invoke_reply(self, id: int, name: str, value: Any) -> None:
+        # called when a node replies to an invoke
         raise NotImplementedError()
 
     def handle_signal(self, name: str, args: Any) -> None:
+        # called when a signal is emitted
         raise NotImplementedError()
 
     def handle_error(self, msgType: int, id: int, error: str) -> None:
+        # called when an error occurs
         raise NotImplementedError()
 
+
 class Protocol(Base):
     listener: IProtocolListener = None
-    def __init__(self, listener: IProtocolListener):   
+
+    def __init__(self, listener: IProtocolListener):
         super()
         self.listener = listener
-    
+
     @staticmethod
     def link_message(name: str) -> list[Any]:
         """links remote object"""
@@ -44,7 +57,8 @@ def link_message(name: str) -> list[Any]:
     @staticmethod
     def init_message(name: str, props: object) -> list[Any]:
         return [MsgType.INIT, name, props]
-    @staticmethod    
+
+    @staticmethod
     def unlink_message(name: str) -> list[Any]:
         """unlinks remote object"""
         return [MsgType.UNLINK, name]
@@ -110,13 +124,7 @@ def handle_message(self, msg: list[Any]) -> bool:
             _, msgType, id, error = msg
             self.listener.handle_error(msgType, id, error)
         else:
-            self.emit_log(LogLevel.DEBUG, f"not supported message type: {msgType}")
+            self.emit_log(LogLevel.DEBUG,
+                          f"not supported message type: {msgType}")
             return False
         return True
-
-
-    
-
-    
-
-