vrpc 2.4.0__tar.gz → 3.0.2__tar.gz

vrpc-3.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Heisenware
+
+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.

vrpc-3.0.2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: vrpc
+Version: 3.0.2
+Summary: Asynchronous remote procedure calls for Python over MQTT
+Author-email: "Dr. Burkhard C. Heisen" <burkhard.heisen@heisenware.com>
+License: MIT License
+        
+        Copyright (c) 2025 Heisenware
+        
+        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.
+        
+Project-URL: Homepage, https://vrpc.io
+Project-URL: Repository, https://github.com/heisenware/vrpc-py
+Project-URL: Issues, https://github.com/heisenware/vrpc-py/issues
+Keywords: rpc,mqtt,async,iot,remote-procedure-call
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiomqtt>=2.0.0
+Requires-Dist: nanoid>=2.0.0
+Requires-Dist: docstring-parser>=0.15
+Requires-Dist: pyee>=11.1.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Dynamic: license-file
+
+# vrpc
+
+> **Variadic Remote Procedure Calls for Python**
+
+`vrpc` is an asynchronous, event-driven Remote Procedure Call (RPC) framework for Python. It allows you to seamlessly expose standard Python classes and functions over an MQTT message broker, making them instantly callable from anywhere in the world.
+
+By leveraging MQTT and Python's `asyncio`, `vrpc` bypasses NATs, firewalls, and complex networking setups, allowing for bi-directional communication, dynamic object instantiation, and remote continuous event streaming.
+
+It is 100% protocol-compatible with the [Node.js / JS `vrpc` implementation](https://github.com/heisenware/vrpc).
+
+## ✨ Features
+
+- **Zero Boilerplate:** Register existing Python classes without modifying their code.
+- **Fully Asynchronous:** Built from the ground up on modern `asyncio` and `aiomqtt`.
+- **Stateful Instances:** Create, manage, and delete remote object instances dynamically. Shared instances can be interacted with by multiple clients simultaneously.
+- **Remote Event Listeners:** Pass Python callables as arguments to remote functions. VRPC automatically binds them to MQTT streams (perfect for real-time sensor data or status updates).
+- **Batch Executions:** Broadcast method calls to all instances of a class across multiple distributed agents in a single line of code (`call_all`).
+
+## 📦 Installation
+
+Since `vrpc` is modern Python package (PEP 621), you can install it directly via pip:
+
+```bash
+pip install vrpc
+```
+
+_Requirements: Python 3.8+_
+
+## 🚀 Quick Start
+
+To use VRPC, you need two components: an **Agent** (which hosts your code) and a **Client** (which remotely calls it). Both connect to a central MQTT broker.
+
+### 1. The Agent (Server)
+
+First, write a standard Python class. Let's create a `Counter` that maintains state and can emit continuous events via a callback.
+
+```python
+# agent.py
+import asyncio
+from vrpc import VrpcAdapter, VrpcAgent
+
+class Counter:
+    def __init__(self, initial_value=0):
+        self._count = initial_value
+        self._callback = None
+
+    def on_change(self, callback):
+        """Registers a callback for continuous state updates."""
+        self._callback = callback
+
+    def increment(self, step=1):
+        """Increments the counter and triggers the callback."""
+        self._count += step
+        if self._callback:
+            self._callback(self._count)
+        return self._count
+
+# 1. Register the class so VRPC knows about it
+VrpcAdapter.register(Counter)
+
+async def main():
+    # 2. Configure the Agent to connect to a broker
+    agent = VrpcAgent(
+        domain="my.custom.domain",
+        agent="python-agent-1",
+        broker="mqtt://broker.hivemq.com:1883" # Public test broker
+    )
+
+    print("Agent is starting...")
+    await agent.serve()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2. The Client
+
+Now, from a completely different machine, process, or network, we can connect a client, create an instance of that `Counter`, and interact with it.
+
+```python
+# client.py
+import asyncio
+from vrpc import VrpcClient
+
+async def main():
+    # 1. Connect to the same broker and domain
+    client = VrpcClient(
+        domain="my.custom.domain",
+        broker="mqtt://broker.hivemq.com:1883"
+    )
+    await client.connect()
+
+    # 2. Create a remote instance of the Counter
+    print("Creating remote Counter instance...")
+    counter = await client.create(
+        agent="python-agent-1",
+        class_name="Counter",
+        instance="my-shared-counter",
+        args=[10]  # Passes '10' to initial_value
+    )
+
+    # 3. Define a local function to handle remote events
+    def handle_update(new_val):
+        print(f" -> Continuous Event Received! Counter is now: {new_val}")
+
+    # VRPC magically wires this Python function over MQTT
+    await counter.on_change(handle_update)
+
+    # 4. Call remote methods
+    print("Calling increment(5)...")
+    result = await counter.increment(5)
+    print(f"RPC Returned: {result}")
+
+    # Cleanup
+    await client.end()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🏗 Architecture Concepts
+
+VRPC organizes remote execution using a specific hierarchy:
+
+- **Domain:** The highest level of isolation. Agents and Clients must share the same domain to see each other.
+- **Agent:** A physical process hosting VRPC code. A single domain can have hundreds of distributed agents.
+- **Class:** A registered Python class available for instantiation.
+- **Instance:** A specific, stateful object created from a Class. Instances can be **Shared** (visible to all clients) or **Isolated** (visible only to the client that created it).
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+1. Fork the project.
+2. Install with test dependencies: `pip install -e .[test]`
+3. Run local adapter tests: `pytest tests/adapter/test_adapter.py`
+4. Run integration tests (requires Docker): `cd tests/agent && ./test.sh`
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

vrpc-3.0.2/README.md

@@ -0,0 +1,141 @@
+# vrpc
+
+> **Variadic Remote Procedure Calls for Python**
+
+`vrpc` is an asynchronous, event-driven Remote Procedure Call (RPC) framework for Python. It allows you to seamlessly expose standard Python classes and functions over an MQTT message broker, making them instantly callable from anywhere in the world.
+
+By leveraging MQTT and Python's `asyncio`, `vrpc` bypasses NATs, firewalls, and complex networking setups, allowing for bi-directional communication, dynamic object instantiation, and remote continuous event streaming.
+
+It is 100% protocol-compatible with the [Node.js / JS `vrpc` implementation](https://github.com/heisenware/vrpc).
+
+## ✨ Features
+
+- **Zero Boilerplate:** Register existing Python classes without modifying their code.
+- **Fully Asynchronous:** Built from the ground up on modern `asyncio` and `aiomqtt`.
+- **Stateful Instances:** Create, manage, and delete remote object instances dynamically. Shared instances can be interacted with by multiple clients simultaneously.
+- **Remote Event Listeners:** Pass Python callables as arguments to remote functions. VRPC automatically binds them to MQTT streams (perfect for real-time sensor data or status updates).
+- **Batch Executions:** Broadcast method calls to all instances of a class across multiple distributed agents in a single line of code (`call_all`).
+
+## 📦 Installation
+
+Since `vrpc` is modern Python package (PEP 621), you can install it directly via pip:
+
+```bash
+pip install vrpc
+```
+
+_Requirements: Python 3.8+_
+
+## 🚀 Quick Start
+
+To use VRPC, you need two components: an **Agent** (which hosts your code) and a **Client** (which remotely calls it). Both connect to a central MQTT broker.
+
+### 1. The Agent (Server)
+
+First, write a standard Python class. Let's create a `Counter` that maintains state and can emit continuous events via a callback.
+
+```python
+# agent.py
+import asyncio
+from vrpc import VrpcAdapter, VrpcAgent
+
+class Counter:
+    def __init__(self, initial_value=0):
+        self._count = initial_value
+        self._callback = None
+
+    def on_change(self, callback):
+        """Registers a callback for continuous state updates."""
+        self._callback = callback
+
+    def increment(self, step=1):
+        """Increments the counter and triggers the callback."""
+        self._count += step
+        if self._callback:
+            self._callback(self._count)
+        return self._count
+
+# 1. Register the class so VRPC knows about it
+VrpcAdapter.register(Counter)
+
+async def main():
+    # 2. Configure the Agent to connect to a broker
+    agent = VrpcAgent(
+        domain="my.custom.domain",
+        agent="python-agent-1",
+        broker="mqtt://broker.hivemq.com:1883" # Public test broker
+    )
+
+    print("Agent is starting...")
+    await agent.serve()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2. The Client
+
+Now, from a completely different machine, process, or network, we can connect a client, create an instance of that `Counter`, and interact with it.
+
+```python
+# client.py
+import asyncio
+from vrpc import VrpcClient
+
+async def main():
+    # 1. Connect to the same broker and domain
+    client = VrpcClient(
+        domain="my.custom.domain",
+        broker="mqtt://broker.hivemq.com:1883"
+    )
+    await client.connect()
+
+    # 2. Create a remote instance of the Counter
+    print("Creating remote Counter instance...")
+    counter = await client.create(
+        agent="python-agent-1",
+        class_name="Counter",
+        instance="my-shared-counter",
+        args=[10]  # Passes '10' to initial_value
+    )
+
+    # 3. Define a local function to handle remote events
+    def handle_update(new_val):
+        print(f" -> Continuous Event Received! Counter is now: {new_val}")
+
+    # VRPC magically wires this Python function over MQTT
+    await counter.on_change(handle_update)
+
+    # 4. Call remote methods
+    print("Calling increment(5)...")
+    result = await counter.increment(5)
+    print(f"RPC Returned: {result}")
+
+    # Cleanup
+    await client.end()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🏗 Architecture Concepts
+
+VRPC organizes remote execution using a specific hierarchy:
+
+- **Domain:** The highest level of isolation. Agents and Clients must share the same domain to see each other.
+- **Agent:** A physical process hosting VRPC code. A single domain can have hundreds of distributed agents.
+- **Class:** A registered Python class available for instantiation.
+- **Instance:** A specific, stateful object created from a Class. Instances can be **Shared** (visible to all clients) or **Isolated** (visible only to the client that created it).
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+1. Fork the project.
+2. Install with test dependencies: `pip install -e .[test]`
+3. Run local adapter tests: `pytest tests/adapter/test_adapter.py`
+4. Run integration tests (requires Docker): `cd tests/agent && ./test.sh`
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

vrpc-3.0.2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vrpc"
+version = "3.0.2"
+description = "Asynchronous remote procedure calls for Python over MQTT"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Dr. Burkhard C. Heisen", email = "burkhard.heisen@heisenware.com"}
+]
+keywords = ["rpc", "mqtt", "async", "iot", "remote-procedure-call"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Core dependencies needed to run the package
+dependencies = [
+    "aiomqtt>=2.0.0",
+    "nanoid>=2.0.0",
+    "docstring-parser>=0.15",
+    "pyee>=11.1.0"
+]
+
+# Optional dependencies for development and testing
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-mock"
+]
+
+[project.urls]
+Homepage = "https://vrpc.io"
+Repository = "https://github.com/heisenware/vrpc-py"
+Issues = "https://github.com/heisenware/vrpc-py/issues"
+
+[tool.pytest.ini_options]
+norecursedirs = "tests/adapter/fixtures"
+asyncio_mode = "auto"