remotestate 0.1.0__tar.gz

remotestate-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

remotestate-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.pixi/
+*.egg-info
+__pycache__/
+.idea/
+.ipynb_checkpoints/
+.venv/
+uv.lock
+dist/

remotestate-0.1.0/LICENSE

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

remotestate-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: remotestate
+Version: 0.1.0
+Summary: Python state, React UI.
+Project-URL: Homepage, https://github.com/bcdev/remotestate
+Project-URL: Issues, https://github.com/bcdev/remotestate/issues
+Project-URL: Repository, https://github.com/bcdev/remotestate
+Author: forman
+License: MIT
+License-File: LICENSE
+Keywords: jupyter,python,react,state,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: fastapi<0.137,>=0.136
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: uvicorn<0.47,>=0.46
+Description-Content-Type: text/markdown
+
+# RemoteState - Python
+
+`remotestate` is the Python runtime for the _RemoteState_ library.
+
+It gives you:
+
+- `Store` for application state
+- `Service` for defining actions and queries
+- `action` and `query` decorators
+- `serve()` for exposing the backend to the React frontend
+
+## Install
+
+```bash
+pip install remotestate
+```
+
+## Quick Start
+
+```python
+import remotestate as rs
+
+store = rs.Store({"count": 0})
+
+
+class MyService(rs.Service):
+    @rs.action
+    async def increment(self):
+        self.store.set("count", self.store.get("count") + 1)
+
+
+rs.serve(MyService(store), dist_dir="my-ui/dist")
+```
+
+For the full project overview, see the repository root README:
+[Remote State](https://github.com/bcdev/remotestate)

remotestate-0.1.0/README.md

@@ -0,0 +1,36 @@
+# RemoteState - Python
+
+`remotestate` is the Python runtime for the _RemoteState_ library.
+
+It gives you:
+
+- `Store` for application state
+- `Service` for defining actions and queries
+- `action` and `query` decorators
+- `serve()` for exposing the backend to the React frontend
+
+## Install
+
+```bash
+pip install remotestate
+```
+
+## Quick Start
+
+```python
+import remotestate as rs
+
+store = rs.Store({"count": 0})
+
+
+class MyService(rs.Service):
+    @rs.action
+    async def increment(self):
+        self.store.set("count", self.store.get("count") + 1)
+
+
+rs.serve(MyService(store), dist_dir="my-ui/dist")
+```
+
+For the full project overview, see the repository root README:
+[Remote State](https://github.com/bcdev/remotestate)

remotestate-0.1.0/TODO.md

@@ -0,0 +1,89 @@
+# remotestate-py To-Dos
+
+## New Features
+
+- [x] Allow serving the UI app from the known URL when running the HTTP dev server
+  serving the Reaact/TypeScript dev app. 
+    - `ui_dist` passed to `serve()` can be a URL.
+    - Include WebSocket URL as query parameter `ws` in opened IFRAME / browser tab.
+
+- [x] Allow enhancing the FastAPI apps by new (HTTP) routes, e.g., to allow for
+  adding an extra REST API. 
+
+- [ ] We currently require a user's `Service` query and action methods to 
+  accept and return JSON data only. Since we use Pydantic, `pydantic.BaseClass`
+  arguments and return values should be handled by default. Allow for custom
+  serielizer/deserializers later (per-service and per-method).
+
+- [ ] Allow calling user `Service` methods on the created `Service` instance.
+  but including their reactive behavior.
+  For this to work, `@action` and `@query` decorators must return wrapped
+  versions of the function that invoke them like if the `action` or `query`
+  came from the frontend. 
+  (Nice, even `task_id` would work with a little effort!)
+  Care: If an action calls actions or queries or a query calls queries the 
+  original method must be called, not the wrapped, reactive version.
+
+## Bugs
+
+- [x] If `ui_dist` passed to `serve()` is a URL, the UI won't work although the 
+  correct WebSocket URL is passed as query parameter `ws` in opened IFRAME.
+
+## Refactorings
+
+- [x] Rename protocol `id` to `call_id`
+- [x] Rename protocol `tid` to `task_id`
+- [x] Rename `InvalidateMessage` to `ActionResultMessage`
+- [x] Rename `"invalidate"` message to `"action_result"`  
+- [x] Rename `Service.process` to `Service.update_task` 
+- [x] Rename `"task_update"` to `"update_task"` 
+
+## Improve error handling 
+
+- [ ] Review Server and Service classes
+- [ ] Visit all critical paths: log or raise or both?
+- [ ] Include traceback in `ErrorMessage`
+
+## State equality
+
+- [ ] Only include values in TaskUpdateMessage that changed. Use `==` by default. 
+      Ensure `InvalidatetMessage` is always sent, even if there are no updates.
+- [ ] Allow passing custom equality checks, register `f(a, b): bool` 
+      using state path as key.
+
+## State serialization
+
+- [ ] Register JSON codec or Pydantic class using state path as key
+
+## State validation
+
+- [ ] Register OpenAPI/JSON schema or Pydantic class using state path as key.
+- [ ] Use schema validate before setting a value 
+
+## Performance
+
+- [ ] Check code for obvious optimization options
+- [ ] Check code for potential performance limitation issues
+- [ ] Check if we can compress request/response sizes, e.g., 
+      have a special binary format for (numpy-like) array data 
+      and (pandas-like) data frames.  
+- [ ] Maybe throttle number emitted TaskUpdateMessage / time
+- [ ] Was using WebSockets + JSON the right decision?
+
+## CI
+
+- [x] Enhance quality checks, e.g., use mypy or similar
+- [x] Create and configure GitHub actions
+
+# remotestate-py Ideas
+
+## Add-on project: TS interface generation
+
+- [ ] A CLI tool to generate a typescript interface and service factory 
+      from a given Python `Service` implementation. The service factory creates
+      a 1:1 TS version of the Python service.
+
+## Add-on project: UI generation
+
+- [ ] Allow for UI generation from OpenAPI/JSON schema. 
+      FieldFactory interface: Neutral w.r.t. UI lib

remotestate-0.1.0/notebooks/basic-usage/index.html

@@ -0,0 +1,59 @@
+<html>
+  <body>
+    <div id="root"></div>
+    <script type="module">
+      import React, { useState, useEffect } from "https://esm.sh/react@19";
+      import { createRoot } from "https://esm.sh/react-dom@19/client";
+
+      const RE = React.createElement;
+
+      // remotestate client inline:
+      // here we use a raw WebSocket without the
+      // remotestate JavaScript library.
+
+      const ws = new WebSocket("ws://localhost:9753/ws");
+
+      ws.onopen = () => {
+        // get initial count
+        ws.send(JSON.stringify({
+          type: "get",
+          id: "1",
+          path: "count",
+        }));
+      };
+
+      function App() {
+        const [count, setCount] = useState(null);
+
+        useEffect(() => {
+          ws.onmessage = (e) => {
+            const msg = JSON.parse(e.data);
+            if (msg.path === "count" || (msg.updates && "count" in msg.updates)) {
+              setCount(msg.value ?? msg.updates.count);
+            }
+          };
+        }, []);
+
+        function handleIncrementClick() {
+          console.log("handleIncrementClick! ws:", ws)
+          ws.send(JSON.stringify({
+            type: "action",
+            call_id: crypto.randomUUID(),
+            task_id: "my-action-call",
+            method: "increment",
+            args: [],
+            kwargs: {},
+          }));
+        }
+
+        return RE("div", null,
+          RE("p", null, `Count: ${count ?? "..."}`),
+          RE("button", { onClick: handleIncrementClick }, "Increment"),
+        );
+      }
+
+      const rootElem = document.getElementById("root");
+      createRoot(rootElem).render(RE(App));
+    </script>
+  </body>
+</html>

remotestate-0.1.0/notebooks/basic-usage.ipynb

@@ -0,0 +1,112 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "d67529d6-1236-41f5-b690-2cb90a71953a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import remotestate as rs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "fc0f8848-1407-4aec-94e2-451112bcfc87",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "store = rs.Store({\"count\": 42, \"user\": {\"name\": \"Norman\"}})"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "b6f59991-d812-4bd1-ae96-bca1d4ed6e46",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class MyService(rs.Service):\n",
+    "    @rs.action\n",
+    "    async def increment(self):\n",
+    "        self.store.set(\"count\", self.store.get(\"count\") + 1)\n",
+    "\n",
+    "    @rs.query\n",
+    "    async def get_count(self) -> int:\n",
+    "        return self.store.get(\"count\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "979719a8-99c0-484e-ba5a-7f41a9f9c0a4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "INFO:     Started server process [17236]\n",
+      "INFO:     Waiting for application startup.\n",
+      "INFO:     Application startup complete.\n",
+      "INFO:     Uvicorn running on http://localhost:9753 (Press CTRL+C to quit)\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "        <iframe\n",
+       "            width=\"100%\"\n",
+       "            height=\"100\"\n",
+       "            src=\"http://localhost:9753?t=1780732089&ws=ws%3A%2F%2Flocalhost%3A9753%2Fws\"\n",
+       "            frameborder=\"0\"\n",
+       "            allowfullscreen\n",
+       "            \n",
+       "        ></iframe>\n",
+       "        "
+      ],
+      "text/plain": [
+       "<IPython.lib.display.IFrame at 0x2253a765550>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "rs.serve(MyService(store), ui_dist=\"./basic-usage\", iframe_height=100)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "22033adc-9d19-415a-89ef-b8b383e6c862",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.14.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

remotestate-0.1.0/notebooks/demo.ipynb

@@ -0,0 +1,139 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "d67529d6-1236-41f5-b690-2cb90a71953a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import remotestate as rs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b5855fdc-6ffc-486e-8172-8202e56f7778",
+   "metadata": {},
+   "source": [
+    "Assumes you have checked out https://github.com/bcdev/remotestate-demo next to this project\n",
+    "and called `npm run build`. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "fc0f8848-1407-4aec-94e2-451112bcfc87",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "store = rs.Store({\"count\": 42})"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "b6f59991-d812-4bd1-ae96-bca1d4ed6e46",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class MyService(rs.Service):\n",
+    "    @rs.action\n",
+    "    async def increment(self):\n",
+    "        self.store.set(\"count\", self.store.get(\"count\") + 1)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "979719a8-99c0-484e-ba5a-7f41a9f9c0a4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "INFO:     Started server process [33104]\n",
+      "INFO:     Waiting for application startup.\n",
+      "INFO:     Application startup complete.\n",
+      "INFO:     Uvicorn running on http://localhost:9753 (Press CTRL+C to quit)\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "        <iframe\n",
+       "            width=\"100%\"\n",
+       "            height=\"300\"\n",
+       "            src=\"http://localhost:9753?t=1780731968&ws=ws%3A%2F%2Flocalhost%3A9753%2Fws\"\n",
+       "            frameborder=\"0\"\n",
+       "            allowfullscreen\n",
+       "            \n",
+       "        ></iframe>\n",
+       "        "
+      ],
+      "text/plain": [
+       "<IPython.lib.display.IFrame at 0x289361323c0>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "INFO:     ::1:49256 - \"GET /?t=1780731968&ws=ws%3A%2F%2Flocalhost%3A9753%2Fws HTTP/1.1\" 200 OK\n",
+      "INFO:     ::1:49256 - \"GET /assets/index-VwyzReuI.js HTTP/1.1\" 200 OK\n",
+      "INFO:     ::1:60640 - \"GET /assets/index-D64VDMd1.css HTTP/1.1\" 200 OK\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "INFO:     ::1:51081 - \"WebSocket /ws\" [accepted]\n",
+      "INFO:     connection open\n"
+     ]
+    }
+   ],
+   "source": [
+    "rs.serve(\n",
+    "    MyService(store), \n",
+    "    # ui_dist=\"http://localhost:5173/\",\n",
+    "    ui_dist=\"../../../remotestate-demo/dist\",\n",
+    "    iframe_height=300,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5a8d1487-8f9f-492b-bc77-69ac1320cd18",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.14.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

remotestate-0.1.0/notebooks/lib-usage/index.html

@@ -0,0 +1,48 @@
+<html>
+  <body>
+    <div id="root"></div>
+    <script type="importmap">
+    {
+      "imports": {
+        "react": "https://esm.sh/react@19",
+        "react-dom/client": "https://esm.sh/react-dom@19/client"
+      }
+    }
+    </script>      
+    <script type="module">
+      import React from "react";
+      import { createRoot } from "react-dom/client";
+      import { RemoteStateProvider, useRemoteStateClient, useRemoteState } from "/dist/remotestate.js";
+
+      const RE = React.createElement;
+
+      function App() {
+        const client = useRemoteStateClient();
+        const [count, setCount] = useRemoteState("count", 0);
+
+        function handleIncrementClick() {
+          client.action("increment");
+        }
+          
+        function handleAddTwoClick() {
+          setCount(count + 2);
+        }
+
+        return RE("div", null,
+          RE("p", null, `Count: ${count}`),
+          RE("button", { onClick: handleIncrementClick }, "Increment"),
+          RE("button", { onClick: handleAddTwoClick }, "Add 2"),
+        );
+      }
+        
+      function Main() {
+        return RE(RemoteStateProvider, { url: "ws://localhost:9755/ws" }, RE(App));
+      }
+
+      console.log("App rendering")
+
+      const rootElem = document.getElementById("root");
+      createRoot(rootElem).render(RE(Main));
+    </script>
+  </body>
+</html>