commlink 0.1.5__tar.gz

commlink-0.1.5/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.5/MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE

commlink-0.1.5/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: commlink
+Version: 0.1.5
+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
+import numpy as np
+from commlink import RPCServer
+
+
+class Robot:
+    def __init__(self):
+        self.name = "robot_arm"
+        self.target = np.zeros(7)
+        self.joint_angles = np.zeros(7)
+
+    def move_to(self, target):
+        """Pretend to command the arm and update internal state."""
+        self.target = target
+        self.joint_angles = target  # Pretend we reached the target.
+        return f"moving to {target}"
+
+    def start_background_planner(self):
+        """Threads inside the object are fine; RPC will just call into them."""
+        # Launch your own planner thread here; omitted for brevity.
+        return "planner started"
+
+
+if __name__ == "__main__":
+    # Wrap the robot with a one-line RPC server. The server runs in a background thread by default.
+    server = RPCServer(Robot(), port=6000)
+    server.start()
+    server.thread.join()  # Optional: keep the process alive while the server thread runs.
+```
+
+### Client
+
+```python
+from commlink import RPCClient
+
+# Pretend the robot is local – all attribute access and calls proxy over the wire.
+robot = RPCClient("localhost", port=6000)
+
+print(robot.name)
+robot.name = "something_else"
+print(robot.name)  # "something_else"
+
+robot.move_to(np.ones(7))
+print(robot.joint_angles)
+
+# Kick off threaded work that lives inside the remote object.
+print(robot.start_background_planner())
+
+# When you're finished, politely stop the remote server.
+robot.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)`.
+* **Thread-friendly** – `RPCServer` can run in a background thread, and the wrapped object can manage its own worker threads or
+  loops without special handling.
+
+## Publisher/subscriber helpers
+
+If you also need broadcast-style messaging (images, poses, strings), Commlink ships with simple ZeroMQ publishers and subscribers:
+
+```python
+import numpy as np
+from commlink import Publisher, Subscriber
+
+pub = Publisher("*", port=5555)
+sub = Subscriber("localhost", port=5555, topics=["rgb_image", "depth_image", "camera_pose", "info"])
+
+# Publish rich data using dict-style access.
+pub["rgb_image"] = np.random.randn(3, 224, 224)
+pub["depth_image"] = np.random.randn(1, 224, 224)
+pub["camera_pose"] = np.random.randn(4, 4)
+pub["info"] = "helloworld"
+
+# Receive them on the subscriber side.
+print(sub["rgb_image"].shape)
+print(sub["depth_image"].shape)
+print(sub["camera_pose"].shape)
+print(sub["info"])
+```
+
+## Development
+
+Run the automated test suite with:
+
+```bash
+pytest
+```
+
+## License
+
+Commlink is distributed under the terms of the [MIT License](./LICENSE).

commlink-0.1.5/README.md

@@ -0,0 +1,113 @@
+# 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
+import numpy as np
+from commlink import RPCServer
+
+
+class Robot:
+    def __init__(self):
+        self.name = "robot_arm"
+        self.target = np.zeros(7)
+        self.joint_angles = np.zeros(7)
+
+    def move_to(self, target):
+        """Pretend to command the arm and update internal state."""
+        self.target = target
+        self.joint_angles = target  # Pretend we reached the target.
+        return f"moving to {target}"
+
+    def start_background_planner(self):
+        """Threads inside the object are fine; RPC will just call into them."""
+        # Launch your own planner thread here; omitted for brevity.
+        return "planner started"
+
+
+if __name__ == "__main__":
+    # Wrap the robot with a one-line RPC server. The server runs in a background thread by default.
+    server = RPCServer(Robot(), port=6000)
+    server.start()
+    server.thread.join()  # Optional: keep the process alive while the server thread runs.
+```
+
+### Client
+
+```python
+from commlink import RPCClient
+
+# Pretend the robot is local – all attribute access and calls proxy over the wire.
+robot = RPCClient("localhost", port=6000)
+
+print(robot.name)
+robot.name = "something_else"
+print(robot.name)  # "something_else"
+
+robot.move_to(np.ones(7))
+print(robot.joint_angles)
+
+# Kick off threaded work that lives inside the remote object.
+print(robot.start_background_planner())
+
+# When you're finished, politely stop the remote server.
+robot.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)`.
+* **Thread-friendly** – `RPCServer` can run in a background thread, and the wrapped object can manage its own worker threads or
+  loops without special handling.
+
+## Publisher/subscriber helpers
+
+If you also need broadcast-style messaging (images, poses, strings), Commlink ships with simple ZeroMQ publishers and subscribers:
+
+```python
+import numpy as np
+from commlink import Publisher, Subscriber
+
+pub = Publisher("*", port=5555)
+sub = Subscriber("localhost", port=5555, topics=["rgb_image", "depth_image", "camera_pose", "info"])
+
+# Publish rich data using dict-style access.
+pub["rgb_image"] = np.random.randn(3, 224, 224)
+pub["depth_image"] = np.random.randn(1, 224, 224)
+pub["camera_pose"] = np.random.randn(4, 4)
+pub["info"] = "helloworld"
+
+# Receive them on the subscriber side.
+print(sub["rgb_image"].shape)
+print(sub["depth_image"].shape)
+print(sub["camera_pose"].shape)
+print(sub["info"])
+```
+
+## Development
+
+Run the automated test suite with:
+
+```bash
+pytest
+```
+
+## License
+
+Commlink is distributed under the terms of the [MIT License](./LICENSE).

commlink-0.1.5/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=67", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "commlink"
+version = "0.1.5"
+description = "ZeroMQ-based publisher/subscriber and RPC utilities"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Commlink Maintainers" }
+]
+keywords = ["zeromq", "messaging", "rpc", "pubsub"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Communications",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "pyzmq>=25.1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+commlink = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

commlink-0.1.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

commlink-0.1.5/src/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-0.1.5/src/commlink/publisher.py

@@ -0,0 +1,54 @@
+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)
+
+    def __setitem__(self, topic: str, data: Any):
+        """
+        Allow dict-style publishing via publisher[topic] = data.
+        """
+        self.publish(topic, data)
+
+
+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-0.1.5/src/commlink/rpc_client.py

@@ -0,0 +1,140 @@
+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()
+        else:
+            raise RuntimeError("Could not stop the server.")
+        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-0.1.5/src/commlink/rpc_server.py

@@ -0,0 +1,153 @@
+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
+        self.thread = None
+        if threaded:
+            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():
+                try:
+                    message = self.socket.recv()
+                    message = pickle.loads(message)
+                    self._handle_message(message)
+                except zmq.ContextTerminated:
+                    break
+        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._send_result(True)
+            self.stop()
+
+    def start(self):
+        if self.threaded:
+            self.stop_event.clear()
+            self.thread = threading.Thread(target=self.run)
+            self.thread.start()
+        else:
+            self.run()
+
+    def stop(self):
+        self.socket.close()
+        self.context.term()
+        if self.threaded:
+            self.stop_event.set()
+            if self.thread and threading.current_thread() is not self.thread:
+                self.thread.join()
+            self.thread = None
+        else:
+            self.stop_event = True
+
+
+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-0.1.5/src/commlink/subscriber.py

@@ -0,0 +1,120 @@
+import pickle
+from typing import Iterable, Optional, Callable, Any
+import warnings
+
+import zmq
+
+
+class Subscriber:
+    def __init__(
+        self,
+        host: str,
+        port: int = 5000,
+        topics: Optional[Iterable[str]] = [],
+        buffer: bool = False,
+    ):
+        """
+        host: host to connect to
+        port: port to connect to
+        topics: optional list of topics to subscribe to.
+            If not supplied, subscribe to all topics.
+        buffer: whether to keep old messages in the buffer (no conflation).
+            Default False (only keep latest for each topic).
+        """
+        self.buffer = buffer
+        self.context = zmq.Context()
+        self.deserializer = pickle.loads
+        self._endpoint = f"tcp://{host}:{port}"
+        self._topic_sockets: dict[Optional[str], zmq.Socket] = {}
+
+        if isinstance(topics, str):
+            raise TypeError("topics must be an iterable of strings, not a single string")
+        else:
+            topics = list(topics)
+            if any(not isinstance(t, str) for t in topics):
+                raise TypeError("topics must be an iterable of strings")
+        if not topics and not buffer:
+            warnings.warn(
+                "Subscribing to all topics with buffer=False keeps only the latest message across all topics."
+                "Specify topics or set buffer=True to avoid this warning.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        self._global_socket = self._new_socket()
+        self._global_socket.setsockopt_string(zmq.SUBSCRIBE, "")
+        self._global_socket.connect(self._endpoint)
+        self._topic_sockets[None] = self._global_socket
+
+        for topic in topics:
+            self._topic_sockets[topic] = self._create_topic_socket(topic)
+
+    def set_deserializer(self, deserializer: Optional[Callable[[bytes], Any]] = None):
+        self.deserializer = deserializer or pickle.loads
+
+    def get(self, topic: Optional[str] = None) -> Any:
+        """
+        Get data for a topic.
+        - sub.get() returns (topic, data) from the global subscriber.
+        - sub.get(topic) returns the deserialized data from that topic's dedicated subscriber.
+        """
+        if topic not in self._topic_sockets:
+            raise KeyError(f"Topic '{topic}' was not subscribed.")
+        msg = self._topic_sockets[topic].recv()
+        topic_str, data_obj = self._deserialize(msg)
+        return (topic_str, data_obj) if topic is None else data_obj
+
+    def __getitem__(self, topic: str) -> Any:
+        """
+        Retrieve data for a specific topic via sub[topic].
+        """
+        return self.get(topic)
+
+    def stop(self):
+        """
+        Safely terminate the subscription and clean up the resources.
+        """
+        for socket in self._topic_sockets.values():
+            socket.close()
+        self.context.term()
+
+    def _new_socket(self) -> zmq.Socket:
+        socket = self.context.socket(zmq.SUB)
+        if not self.buffer:
+            socket.setsockopt(zmq.CONFLATE, 1)
+        return socket
+
+    def _create_topic_socket(self, topic: str) -> zmq.Socket:
+        self._validate_topic(topic)
+        socket = self._new_socket()
+        socket.setsockopt_string(zmq.SUBSCRIBE, topic)
+        socket.connect(self._endpoint)
+        return socket
+
+    def _validate_topic(self, topic: str):
+        if " " in topic:
+            raise ValueError("topic cannot contain spaces")
+
+    def _deserialize(self, msg: bytes) -> tuple[str, Any]:
+        topic = msg.split(b" ")[0].decode("utf-8")
+        data = msg[len(topic) + 1 :]
+        data_obj = self.deserializer(data)
+        return topic, data_obj
+
+
+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.5/src/commlink.egg-info/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: commlink
+Version: 0.1.5
+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
+import numpy as np
+from commlink import RPCServer
+
+
+class Robot:
+    def __init__(self):
+        self.name = "robot_arm"
+        self.target = np.zeros(7)
+        self.joint_angles = np.zeros(7)
+
+    def move_to(self, target):
+        """Pretend to command the arm and update internal state."""
+        self.target = target
+        self.joint_angles = target  # Pretend we reached the target.
+        return f"moving to {target}"
+
+    def start_background_planner(self):
+        """Threads inside the object are fine; RPC will just call into them."""
+        # Launch your own planner thread here; omitted for brevity.
+        return "planner started"
+
+
+if __name__ == "__main__":
+    # Wrap the robot with a one-line RPC server. The server runs in a background thread by default.
+    server = RPCServer(Robot(), port=6000)
+    server.start()
+    server.thread.join()  # Optional: keep the process alive while the server thread runs.
+```
+
+### Client
+
+```python
+from commlink import RPCClient
+
+# Pretend the robot is local – all attribute access and calls proxy over the wire.
+robot = RPCClient("localhost", port=6000)
+
+print(robot.name)
+robot.name = "something_else"
+print(robot.name)  # "something_else"
+
+robot.move_to(np.ones(7))
+print(robot.joint_angles)
+
+# Kick off threaded work that lives inside the remote object.
+print(robot.start_background_planner())
+
+# When you're finished, politely stop the remote server.
+robot.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)`.
+* **Thread-friendly** – `RPCServer` can run in a background thread, and the wrapped object can manage its own worker threads or
+  loops without special handling.
+
+## Publisher/subscriber helpers
+
+If you also need broadcast-style messaging (images, poses, strings), Commlink ships with simple ZeroMQ publishers and subscribers:
+
+```python
+import numpy as np
+from commlink import Publisher, Subscriber
+
+pub = Publisher("*", port=5555)
+sub = Subscriber("localhost", port=5555, topics=["rgb_image", "depth_image", "camera_pose", "info"])
+
+# Publish rich data using dict-style access.
+pub["rgb_image"] = np.random.randn(3, 224, 224)
+pub["depth_image"] = np.random.randn(1, 224, 224)
+pub["camera_pose"] = np.random.randn(4, 4)
+pub["info"] = "helloworld"
+
+# Receive them on the subscriber side.
+print(sub["rgb_image"].shape)
+print(sub["depth_image"].shape)
+print(sub["camera_pose"].shape)
+print(sub["info"])
+```
+
+## Development
+
+Run the automated test suite with:
+
+```bash
+pytest
+```
+
+## License
+
+Commlink is distributed under the terms of the [MIT License](./LICENSE).

commlink-0.1.5/src/commlink.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/commlink/__init__.py
+src/commlink/publisher.py
+src/commlink/py.typed
+src/commlink/rpc_client.py
+src/commlink/rpc_server.py
+src/commlink/subscriber.py
+src/commlink.egg-info/PKG-INFO
+src/commlink.egg-info/SOURCES.txt
+src/commlink.egg-info/dependency_links.txt
+src/commlink.egg-info/requires.txt
+src/commlink.egg-info/top_level.txt
+tests/test_pubsub.py
+tests/test_rpc.py

commlink-0.1.5/src/commlink.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

commlink-0.1.5/src/commlink.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyzmq>=25.1
+
+[test]
+pytest>=7

commlink-0.1.5/src/commlink.egg-info/top_level.txt

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

commlink-0.1.5/tests/test_pubsub.py

@@ -0,0 +1,167 @@
+import socket
+import time
+
+import pytest
+import zmq
+
+from commlink.publisher import Publisher
+from commlink.subscriber import Subscriber
+
+
+def get_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def set_receive_timeouts(subscriber: Subscriber, timeout_ms: int = 1000) -> None:
+    subscriber._global_socket.setsockopt(zmq.RCVTIMEO, timeout_ms)
+    for socket in subscriber._topic_sockets.values():
+        socket.setsockopt(zmq.RCVTIMEO, timeout_ms)
+
+
+def test_multi_topic_specific_sockets_keep_latest_message():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["alpha", "beta"], buffer=False)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher.publish("alpha", "first-alpha")
+    publisher.publish("beta", "first-beta")
+    publisher.publish("alpha", "second-alpha")
+    publisher.publish("beta", "second-beta")
+    time.sleep(0.05)
+
+    data_a = subscriber.get("alpha")
+    assert data_a == "second-alpha"
+
+    data_b = subscriber.get("beta")
+    assert data_b == "second-beta"
+
+    subscriber.stop()
+
+
+def test_global_get_receives_messages_from_all_topics():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["one", "two"], buffer=True)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher.publish("one", 1)
+    publisher.publish("two", 2)
+
+    received_topics = []
+    for _ in range(2):
+        topic, data = subscriber.get()
+        received_topics.append(topic)
+        assert data in (1, 2)
+
+    assert set(received_topics) == {"one", "two"}
+
+    subscriber.stop()
+
+
+def test_getitem_reads_specific_topic_socket():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["red", "blue"], buffer=False)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher.publish("blue", "other")
+    publisher.publish("red", "stale")
+    publisher.publish("red", "fresh")
+    time.sleep(0.05)
+
+    data = subscriber["red"]
+    assert data == "fresh"
+
+    subscriber.stop()
+
+
+def test_setitem_publishes():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["alpha"], buffer=False)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher["alpha"] = "published via setitem"
+    time.sleep(0.05)
+
+    assert subscriber["alpha"] == "published via setitem"
+
+    subscriber.stop()
+
+
+def test_get_raises_for_unsubscribed_topic():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["alpha"], buffer=False)
+    set_receive_timeouts(subscriber)
+    time.sleep(0.05)
+
+    with pytest.raises(KeyError):
+        subscriber.get("beta")
+
+    publisher.publish("alpha", "value")
+    time.sleep(0.05)
+    assert subscriber.get("alpha") == "value"
+
+    subscriber.stop()
+
+
+def test_global_subscription_with_empty_topics_list():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=[], buffer=True)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher.publish("x", "first")
+    publisher.publish("y", "second")
+
+    received = {subscriber.get()[0], subscriber.get()[0]}
+    assert received == {"x", "y"}
+
+    subscriber.stop()
+
+
+def test_topic_validation_rejects_spaces():
+    port = get_free_port()
+    with pytest.raises(ValueError):
+        Subscriber("127.0.0.1", port=port, topics=["bad topic"], buffer=True)
+
+
+def test_buffer_true_preserves_order_on_topic_socket():
+    port = get_free_port()
+    publisher = Publisher("*", port=port)
+    subscriber = Subscriber("127.0.0.1", port=port, topics=["seq"], buffer=True)
+    set_receive_timeouts(subscriber)
+
+    time.sleep(0.05)
+    publisher.publish("seq", 1)
+    publisher.publish("seq", 2)
+    time.sleep(0.05)
+
+    first = subscriber.get("seq")
+    second = subscriber.get("seq")
+    assert first == 1
+    assert second == 2
+
+    subscriber.stop()
+
+
+def test_conflate_global_subscription_rejected():
+    port = get_free_port()
+    with pytest.warns(RuntimeWarning):
+        sub_empty = Subscriber("127.0.0.1", port=port, topics=[], buffer=False)
+        sub_empty.stop()
+
+
+def test_topics_str_is_normalized_to_list():
+    port = get_free_port()
+    with pytest.raises(TypeError):
+        Subscriber("127.0.0.1", port=port, topics="solo", buffer=False)

commlink-0.1.5/tests/test_rpc.py

@@ -0,0 +1,107 @@
+import socket
+import threading
+import time
+
+import pytest
+
+from commlink.rpc_client import RPCClient, RPCException
+from commlink.rpc_server import RPCServer
+
+
+class ExampleService:
+    def __init__(self):
+        self.value = 0
+
+    def increment(self, amount: int = 1) -> int:
+        self.value += amount
+        return self.value
+
+    def raise_error(self) -> None:
+        raise ValueError("boom")
+
+
+def get_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def start_server(service: ExampleService, port: int, threaded: bool):
+    server = RPCServer(service, port=port, threaded=threaded)
+    if threaded:
+        server.start()
+        server_thread = server.thread
+    else:
+        server_thread = threading.Thread(target=server.start, daemon=True)
+        server_thread.start()
+    time.sleep(0.05)
+    return server, server_thread
+
+
+@pytest.mark.parametrize("threaded", [True, False])
+def test_rpc_server_start_stop(threaded):
+    port = get_free_port()
+    service = ExampleService()
+    server, server_thread = start_server(service, port, threaded)
+    try:
+        if threaded:
+            assert server.thread is not None
+            assert server.thread.is_alive()
+            server.stop()
+            assert server.thread is None
+        else:
+            assert server_thread is not None
+            server.stop()
+            server_thread.join(timeout=1)
+            assert not server_thread.is_alive()
+    finally:
+        if threaded:
+            if server.thread is not None:
+                server.stop()
+        else:
+            if server_thread is not None and server_thread.is_alive():
+                server.stop()
+                server_thread.join(timeout=1)
+
+
+def test_rpc_client_connect():
+    port = get_free_port()
+    service = ExampleService()
+    server, server_thread = start_server(service, port, threaded=True)
+    try:
+        client = RPCClient("127.0.0.1", port=port)
+        assert "increment" in dir(client)
+    finally:
+        if server.thread is not None:
+            server.stop()
+
+
+@pytest.mark.parametrize("threaded", [True, False])
+def test_rpc_server_client_integration(threaded):
+    port = get_free_port()
+    service = ExampleService()
+    server, server_thread = start_server(service, port, threaded)
+    client = RPCClient("127.0.0.1", port=port)
+    try:
+        assert client.increment(5) == 5
+        assert client.value == 5
+
+        client.value = 42
+        assert client.value == 42
+
+        with pytest.raises(RPCException) as exc:
+            client.raise_error()
+        assert "ValueError" in str(exc.value)
+
+        stop_result = client.stop_server()
+        assert stop_result is True
+    finally:
+        if server_thread is not None:
+            server_thread.join(timeout=1)
+        if threaded:
+            if server.thread is not None:
+                server.stop()
+        else:
+            if server_thread is not None and server_thread.is_alive():
+                server.stop()
+                server_thread.join(timeout=1)