commlink 0.1.1__py3-none-any.whl

commlink/__init__.py

@@ -0,0 +1,16 @@
+"""Commlink package exposing ZeroMQ-based publisher, subscriber, and RPC helpers."""
+
+from .publisher import Publisher
+from .subscriber import Subscriber
+from .rpc_client import RPCClient, RPCException
+from .rpc_server import RPCServer
+
+__all__ = [
+    "Publisher",
+    "Subscriber",
+    "RPCClient",
+    "RPCException",
+    "RPCServer",
+]
+
+__version__ = "0.1.0"

commlink/publisher.py

@@ -0,0 +1,48 @@
+import zmq
+import pickle
+from typing import Optional, Callable, Any
+
+
+class Publisher:
+    def __init__(self, host: str, port: int = 5000):
+        """
+        host: host to connect to
+        port: port to connect to
+        """
+        self.context = zmq.Context()
+        self.socket = self.context.socket(zmq.PUB)
+        self.socket.bind(f"tcp://{host}:{port}")
+        self.serializer = pickle.dumps
+
+    def set_serializer(self, serializer: Optional[Callable[[Any], bytes]]):
+        self.serializer = serializer or pickle.dumps
+
+    def publish(self, topic: str, data: Any):
+        """
+        Publish a dictionary of {
+            "topic": str,
+            "data": object,
+        }
+        where the data is serialized using self.serializer (default: pickle.dumps)
+        """
+        if " " in topic:
+            raise ValueError("topic cannot contain spaces")
+        topic = topic.encode("utf-8")
+        data = self.serializer(data)
+        msg = topic + b" " + data
+        self.socket.send(msg)
+
+
+if __name__ == "__main__":
+    # Example usage:
+    import numpy as np
+
+    def np_array_serializer(arr):
+        return arr.tobytes()
+
+    if __name__ == "__main__":
+        pub = Publisher("*", port=1234)
+        pub.set_serializer(np_array_serializer)
+
+        while True:
+            pub.publish("test", np.random.rand(100, 100))

commlink/rpc_client.py

@@ -0,0 +1,138 @@
+import zmq
+import pickle
+
+
+class RPCException(Exception):
+    def __init__(self, exception_type: str, message: str, traceback: str):
+        self.exception_type = exception_type
+        self.message = message
+        self.traceback = traceback
+
+    def __str__(self):
+        return f"{self.exception_type}: {self.message}\n{self.traceback}"
+
+
+class RPCClient:
+    def __init__(self, host: str, port: int = 5000):
+        """
+        host: host to connect to
+        port: port to connect to
+        """
+        self.__dict__["context"] = zmq.Context()
+        self.__dict__["socket"] = self.context.socket(zmq.REQ)
+        self.socket.connect(f"tcp://{host}:{port}")
+        self.__dict__["_is_callable_cache"] = {}
+
+    def __setattr__(self, attr: str, value):
+        """
+        Set the attribute of the same name.
+        Attribute must not be callable on remote.
+        """
+        if self._is_callable(attr):
+            raise AttributeError(f"Overwriting a callable attribute: {attr}")
+        self._send_set(attr, value)
+
+    def _send_get(self, attr: str, args: list, kwargs: dict):
+        """
+        Send a get request over the socket.
+        """
+        req = {"req": "get", "attr": attr, "args": args, "kwargs": kwargs}
+        self.socket.send(pickle.dumps(req))
+        return self._recv_result()
+
+    def _send_set(self, attr: str, value):
+        """
+        Send a set request over the socket.
+        """
+        req = {"req": "set", "attr": attr, "value": value}
+        self.socket.send(pickle.dumps(req))
+        return self._recv_result()
+
+    def _recv_result(self):
+        """
+        Receive a dictionary of {
+            "type": str,
+            "content": object,
+        }
+        if type == "exception", content is a dictionary of {
+            "exception": str,
+            "message": str,
+            "traceback": str,
+        }; re-raise the exception on the client side
+        if type == "result", content is the result
+        """
+        result = self.socket.recv()
+        result = pickle.loads(result)
+        if result["type"] == "exception":
+            raise RPCException(
+                result["content"]["exception"],
+                result["content"]["message"],
+                result["content"]["traceback"],
+            )
+        return result["content"]
+
+    def _is_callable(self, attr: str) -> bool:
+        """
+        Send a request to check if the attribute is callable.
+        Returns False if the attribute is not found.
+        """
+        if attr not in self._is_callable_cache:
+            req = {"req": "is_callable", "attr": attr}
+            self.socket.send(pickle.dumps(req))
+            result = self._recv_result()
+            self._is_callable_cache[attr] = result
+        return self._is_callable_cache[attr]
+
+    def __getattr__(self, attr: str):
+        """
+        Return the attribute of the same name.
+        If the attribute is a callable, return a function that sends the call over the socket.
+        Else, return the attribute value.
+        """
+        if self._is_callable(attr):
+            return lambda *args, **kwargs: self._send_get(attr, args, kwargs)
+        else:
+            return self._send_get(attr, [], {})
+
+    def __dir__(self):
+        """
+        Return a list of attributes.
+        """
+        req = {"req": "dir"}
+        self.socket.send(pickle.dumps(req))
+        result = self._recv_result()
+        return result + ["stop_server"]
+
+    def stop_server(self) -> bool:
+        """
+        Send a stop request to the server.
+        If the server is stopped, close the socket and terminate the context.
+        Returns a bool for success.
+        """
+        req = {"req": "stop"}
+        self.socket.send(pickle.dumps(req))
+        stopped = self._recv_result()
+        if stopped:
+            self.socket.close()
+            self.context.term()
+        return stopped
+
+
+if __name__ == "__main__":
+    import time
+    import numpy as np
+
+    Hello = RPCClient("localhost", port=1234)
+    arr = []
+    for i in range(100):
+        start = time.time()
+        print(Hello.hello())
+        arr.append(time.time() - start)
+    print("Total time:", sum(arr))
+    print(sum(arr) / len(arr))
+    print(len(arr) / sum(arr))
+    print(Hello.abc)
+    Hello.new_attr = 456
+    print(Hello.new_attr)
+    print(dir(Hello))
+    print(Hello.bad())

commlink/rpc_server.py

@@ -0,0 +1,149 @@
+import zmq
+import time
+import pickle
+import threading
+import traceback
+
+
+class RPCServer:
+    def __init__(self, obj, port: int = 5000, threaded: bool = True):
+        """
+        obj: object with methods to expose
+        port: port to listen on
+        """
+        self.obj = obj
+        self.context = zmq.Context()
+        self.socket: zmq.socket.Socket = self.context.socket(zmq.REP)
+        self.socket.bind(f"tcp://*:{port}")
+        self.threaded = threaded
+        if threaded:
+            self.thread = threading.Thread(target=self.run)
+            self.stop_event = threading.Event()
+        else:
+            self.stop_event = False
+
+    def _send_exception(self, e):
+        """
+        Serialize an exception and send it over the socket.
+        Only the exception type, message, and traceback are sent.
+        """
+        exception = {
+            "type": "exception",
+            "content": {
+                "exception": str(type(e)),
+                "message": str(e),
+                "traceback": traceback.format_exc(),
+            },
+        }
+        self.socket.send(pickle.dumps(exception))
+
+    def _send_result(self, result):
+        """
+        Serialize a result and send it over the socket.
+        """
+        result = {"type": "result", "content": result}
+        self.socket.send(pickle.dumps(result))
+
+    def run(self):
+        """
+        Run the server.
+        """
+        if self.threaded:
+            while not self.stop_event.is_set():
+                message = self.socket.recv()
+                message = pickle.loads(message)
+                self._handle_message(message)
+        else:
+            while not self.stop_event:
+                try:
+                    message = self.socket.recv(flags=zmq.NOBLOCK)
+                    message = pickle.loads(message)
+                except zmq.Again:
+                    time.sleep(0.001)
+                    continue
+                self._handle_message(message)
+
+    def _is_callable(self, attr):
+        return hasattr(self.obj, attr) and callable(getattr(self.obj, attr))
+
+    def _handle_message(self, message):
+        """
+        Handles a dictionary of {
+            "req": str,  # request type
+            "attr": str,
+            "args": list,
+            "kwargs": dict,
+        }
+        from the socket.
+        If req == "is_callable", return whether the attribute is callable.
+        If req == "get", return the attribute.
+            If the attribute is not found, return an error message.
+            If the attribute is callable, call with args and kwargs.
+                If there are any errors in the callable, return the pickled error
+                If the callable is found and there are no errors, return the pickled result.
+            If the attribute is not callable, return the attribute.
+        If req == "set", set the attribute to the value.
+        If req == "dir", return a list of attributes.
+        If req == "stop", stop the server.
+        """
+        if message["req"] == "is_callable":
+            result = self._is_callable(message["attr"])
+            self._send_result(result)
+        elif message["req"] == "get":
+            try:
+                attribute = getattr(self.obj, message["attr"])
+                args = message["args"]
+                kwargs = message["kwargs"]
+                if not callable(attribute):
+                    self._send_result(attribute)
+                else:
+                    result = attribute(*args, **kwargs)
+                    self._send_result(result)
+            except Exception as e:
+                self._send_exception(e)
+        elif message["req"] == "set":
+            try:
+                setattr(self.obj, message["attr"], message["value"])
+                self._send_result(None)
+            except Exception as e:
+                self._send_exception(e)
+        elif message["req"] == "dir":
+            result = dir(self.obj)
+            self._send_result(result)
+        elif message["req"] == "stop":
+            self.stop()
+
+    def close(self):
+        self.socket.close()
+        self.context.term()
+
+    def start(self):
+        if self.threaded:
+            self.stop_event.clear()
+            self.thread.start()
+        else:
+            self.run()
+
+    def stop(self):
+        if self.threaded:
+            self.stop_event.set()
+            self.thread.join()
+        else:
+            self.stop_event = True
+        self.close()
+
+
+if __name__ == "__main__":
+    import numpy as np
+    class HelloWorld:
+        def __init__(self):
+            self.abc = 123
+
+        def hello(self):
+            return np.random.randn(3, 224, 224)
+
+        def bad(self):
+            return 1 / 0
+
+    server = RPCServer(HelloWorld(), port=1234)
+    server.start()

commlink/subscriber.py

@@ -0,0 +1,70 @@
+import zmq
+import pickle
+from typing import Iterable, Optional, Callable, Any
+
+
+class Subscriber:
+    def __init__(
+        self,
+        host: str,
+        port: int = 5000,
+        topics: Optional[Iterable[str]] = None,
+        keep_old: bool = False,
+    ):
+        """
+        host: host to connect to
+        port: port to connect to
+        topics: optional iterable of topics to subscribe to.
+            If ``None``, subscribe to all topics.
+        keep_old: whether to keep old messages in the buffer.
+            Default False (only keep the latest message).
+        """
+        self.context = zmq.Context()
+        self.socket = self.context.socket(zmq.SUB)
+        self.deserializer = pickle.loads
+        if topics is not None:
+            for topic in topics:
+                if " " in topic:
+                    raise ValueError("topic cannot contain spaces")
+                self.socket.setsockopt_string(zmq.SUBSCRIBE, topic)
+        if not keep_old:
+            self.socket.setsockopt(zmq.CONFLATE, 1)
+        self.socket.connect(f"tcp://{host}:{port}")
+
+    def set_deserializer(self, deserializer: Optional[Callable[[bytes], Any]]):
+        self.deserializer = deserializer or pickle.loads
+
+    def get(self) -> tuple[str, Any]:
+        """
+        Get a tuple of (topic, data) where data is deserialized using self.deserializer (default: pickle.loads). If no message is available, this will block until one is available.
+        """
+        msg = self.socket.recv()
+        topic = msg.split(b" ")[0].decode("utf-8")
+        data = msg[len(topic) + 1 :]
+        data_obj = self.deserializer(data)
+        return topic, data_obj
+
+    def stop(self):
+        """
+        Safely terminate the subscription and clean up the resources.
+        """
+        self.socket.close()
+        self.context.term()
+
+
+if __name__ == "__main__":
+    # Example usage:
+    import cv2
+    import numpy as np
+
+    def np_array_deserializer(arr):
+        return np.frombuffer(arr, dtype=np.float64).reshape((100, 100))
+
+    sub = Subscriber("localhost", port=1234, topics=["test"])
+    sub.set_deserializer(np_array_deserializer)
+
+    while True:
+        topic, data = sub.get()
+        print(topic)
+        cv2.imshow("test", data)
+        cv2.waitKey(1)

commlink-0.1.1.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: commlink
+Version: 0.1.1
+Summary: ZeroMQ-based publisher/subscriber and RPC utilities
+Author: Commlink Maintainers
+License: MIT License
+        
+        Copyright (c) 2024 Commlink Maintainers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: zeromq,messaging,rpc,pubsub
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyzmq>=25.1
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Commlink
+
+Commlink exposes a lightweight Remote Procedure Call (RPC) layer on top of [ZeroMQ](https://zeromq.org/) that lets you interact
+with objects running in a different process or host as if they were local. You can wrap any existing object with a single line
+and obtain a client-side proxy that transparently mirrors attribute access, mutation, and callable invocation for anything that
+can be pickled. Simple publisher/subscriber helpers are also available for broadcast-style messaging when you need them.
+
+## Installation
+
+```bash
+pip install commlink
+```
+
+## RPC quickstart
+
+### Server
+
+```python
+from commlink import RPCServer
+
+
+class TemperatureController:
+    def __init__(self):
+        self.target_celsius = 20
+
+    def get_reading(self):
+        """Pretend to talk to a sensor and return the current reading."""
+        return self.target_celsius
+
+    def setpoint(self, value):
+        self.target_celsius = value
+        return f"Set target temperature to {value}°C"
+
+
+if __name__ == "__main__":
+    # Wrap the object with a one-line RPC server. The server runs in a background thread by default.
+    server = RPCServer(TemperatureController(), port=6000)
+    server.start()
+    server.thread.join()  # Optional: keep the process alive while the server thread runs.
+```
+
+### Client
+
+```python
+from commlink import RPCClient
+
+# Instantiate the remote object locally – attribute access, setters, and method calls all proxy to the server.
+controller = RPCClient("localhost", port=6000)
+
+print(controller.get_reading())  # Call remote methods with any pickle-able arguments or return values.
+print(controller.setpoint(25))
+
+controller.target_celsius = 18  # Mutate attributes on the remote instance.
+print(controller.target_celsius)
+
+# When you're finished, politely stop the remote server.
+controller.stop_server()
+```
+
+### RPC capabilities
+
+* **Transparent calls** – Functions and methods execute remotely with arbitrary pickle-able arguments and return values.
+* **Attribute access** – Reading or setting attributes forwards the operation to the remote object.
+* **Drop-in adoption** – Wrap any pre-existing object with `RPCServer(obj, ...)` and obtain a live proxy by instantiating
+  `RPCClient(host, port)`.
+* **Threaded by default** – `RPCServer` starts in a background thread so your host application can continue doing work or cleanly
+  manage lifecycle events.
+
+## Publisher/subscriber helpers
+
+If you also need broadcast-style messaging, Commlink ships with simple ZeroMQ publishers and subscribers:
+
+```python
+from commlink import Publisher, Subscriber
+
+publisher = Publisher("*", port=5555)
+subscriber = Subscriber("localhost", port=5555, topics=["updates"])
+
+publisher.publish("updates", {"message": "Hello, world!"})
+print(subscriber.get())
+```
+
+## Development
+
+Run the automated test suite with:
+
+```bash
+pytest
+```
+
+## License
+
+Commlink is distributed under the terms of the [MIT License](./LICENSE).

commlink-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+commlink/__init__.py,sha256=3tivTOl6cENhsqde-suWICfd5smKY7N9fKGykwll_mo,363
+commlink/publisher.py,sha256=SCcd0PzDg01Venx9k_Gscv4_s6noj_oGKwRQ03q4i_Y,1348
+commlink/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commlink/rpc_client.py,sha256=HyWh8GBD5METuJtF0a6jRPVK7MZq9KlE91Bzw0iLYr4,4342
+commlink/rpc_server.py,sha256=hwbWYcca0x9nlYoCAn3_Sx1-IK7d9foBpGbfw-bLR7Q,4752
+commlink/subscriber.py,sha256=K67CQjBPVipYmppA5KwtLd5_KtJY-Bz-rmCdyizT23c,2256
+commlink-0.1.1.dist-info/licenses/LICENSE,sha256=uQ1aP6bBL-De6FbtpF-zfd_Z3NAnrgPpZOqmLJTYL38,1077
+commlink-0.1.1.dist-info/METADATA,sha256=SbcqVN3HdYRMwaxEODyQxDjpFKcLBgYdmW20It3dbDI,5013
+commlink-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+commlink-0.1.1.dist-info/top_level.txt,sha256=BR-bDZjiEe9vW1Zy6qKGI0LNJoUyvfAEyi0QFzvEBYQ,9
+commlink-0.1.1.dist-info/RECORD,,

commlink-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commlink-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Commlink Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commlink-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+commlink