hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/backends/granian.py

@@ -0,0 +1,276 @@
+"""基于 Starlette + Granian 的 Hyperdiv 后端。
+
+设计约束：`AppRunner` 只依赖连接对象的 `send(message: dict)`，且该调用是
+同步的（由 AppRunner 的工作线程发起）。因此这里的 WebSocket 适配器必须
+提供一个 *同步* 的 `send`，内部把协程投递回 WebSocket 所在的 asyncio
+事件循环执行，避免修改上游 `app_runner.py`。
+
+与 Tornado 后端的语义对齐点：
+- `/ws` 接受 `clientId` / `updates` 查询参数，收到 JSON 消息后汇总 updates；
+- 静态资源找不到时回落到 index 页面（支持任意 Hyperdiv 路径）；
+- 插件资源走 `/hyperdiv-plugins/<plugin>/<path>`；
+- 应用目录下的 `assets/` 映射到 `/assets/`。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import os
+import sys
+import threading
+import uuid
+from urllib.parse import parse_qs
+
+from starlette.applications import Starlette
+from starlette.responses import FileResponse, HTMLResponse, Response
+from starlette.routing import Route, WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from ..app_runner import AppRunner
+from ..debug import logger
+from ..frontend import get_frontend_public_path
+from ..plugin import PLUGINS_PREFIX, PluginAssetsCollector
+
+
+class Connection:
+    """ASGI WebSocket 会话，接口与 Tornado 版 Connection 对齐。"""
+
+    _active_connections: dict[uuid.UUID, "Connection"] = {}
+
+    def __init__(self, websocket: WebSocket, app_function, task_runtime):
+        self.websocket = websocket
+        self.loop = asyncio.get_running_loop()
+        self.client_id = uuid.uuid4()
+        Connection._active_connections[self.client_id] = self
+
+        updates = []
+        raw_updates = websocket.query_params.get("updates")
+        if raw_updates:
+            try:
+                updates = json.loads(raw_updates)
+            except Exception as e:  # noqa: BLE001 - 与上游一致，容错
+                logger.warning(f"Corrupted `updates` argument: {e}")
+
+        self.runner = AppRunner(self, task_runtime, app_function, updates)
+
+    def send(self, message: dict) -> None:
+        """同步下发消息（AppRunner 在工作线程中调用）。"""
+        try:
+            future = asyncio.run_coroutine_threadsafe(
+                self.websocket.send_json(message), self.loop
+            )
+            # 不阻塞等待，让渲染线程继续；异常在回调里记录。
+            future.add_done_callback(self._log_failure)
+        except RuntimeError:
+            # 事件循环已关闭，说明连接正在销毁。
+            pass
+
+    @staticmethod
+    def _log_failure(future) -> None:
+        try:
+            future.result()
+        except Exception as e:  # noqa: BLE001
+            logger.debug(f"Failed to write to client: {e}")
+
+    async def serve(self) -> None:
+        await self.websocket.accept()
+        logger.info(
+            "Connection opened. %d connections open."
+            % len(Connection._active_connections)
+        )
+        try:
+            self.runner.start()
+            while True:
+                raw = await self.websocket.receive_text()
+                self._on_message(raw)
+        except WebSocketDisconnect:
+            pass
+        except Exception as e:  # noqa: BLE001
+            logger.exception(f"WebSocket error: {e}")
+        finally:
+            self.runner.stop()
+            Connection._active_connections.pop(self.client_id, None)
+            logger.info(
+                "Connection closed. %d connections open."
+                % len(Connection._active_connections)
+            )
+
+    def _on_message(self, raw: str) -> None:
+        try:
+            messages = json.loads(raw)
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"Corrupted WebSocket message: {e}")
+            return
+        ui_updates = []
+        for m in messages:
+            ui_updates.extend(m["updates"])
+        self.runner.enqueue_ui_updates(ui_updates)
+
+    @staticmethod
+    def close_all_connections() -> None:
+        logger.info(f"Closing {len(Connection._active_connections)} connections.")
+        for conn in list(Connection._active_connections.values()):
+            conn.runner.stop()
+
+
+def _guess_content_type(path: str) -> str:
+    """按扩展名返回静态资源的 content-type。"""
+    ext = os.path.splitext(path)[1].lower()
+    return {
+        ".html": "text/html; charset=utf-8",
+        ".js": "text/javascript; charset=utf-8",
+        ".mjs": "text/javascript; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".json": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".ico": "image/x-icon",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf",
+        ".map": "application/json",
+        ".txt": "text/plain; charset=utf-8",
+    }.get(ext, "application/octet-stream")
+
+
+def _safe_join(root: str, relative: str) -> str | None:
+    """把相对路径安全地拼到 root 下，拒绝越界访问。"""
+    relative = relative.lstrip("/")
+    candidate = os.path.realpath(os.path.join(root, relative))
+    root_real = os.path.realpath(root)
+    if candidate == root_real or candidate.startswith(root_real + os.sep):
+        return candidate
+    return None
+
+
+def build_asgi_app(app_function, task_runtime, index_page: str) -> Starlette:
+    """构造与 Tornado 路由行为等价的 Starlette 应用。"""
+    public_path = get_frontend_public_path()
+    index_bytes = index_page.encode("utf-8")
+    modified_time = datetime.datetime.now()
+
+    assets_dir = os.path.join(os.path.dirname(os.path.abspath(sys.argv[0])), "assets")
+
+    async def websocket_endpoint(websocket: WebSocket) -> None:
+        conn = Connection(websocket, app_function, task_runtime)
+        await conn.serve()
+
+    async def index_endpoint(request) -> Response:
+        return HTMLResponse(
+            content=index_bytes,
+            headers={"Last-Modified": modified_time.strftime("%a, %d %b %Y %H:%M:%S GMT")},
+        )
+
+    async def plugin_assets_endpoint(request) -> Response:
+        raw = request.path_params["path"]
+        plugin_name, _, asset_path = raw.partition("/")
+        config = PluginAssetsCollector.plugin_assets.get(plugin_name)
+        if not config or not asset_path:
+            return Response(status_code=404)
+        target = _safe_join(config["assets_root"], asset_path)
+        if not target or not os.path.isfile(target):
+            return Response(status_code=404)
+        return FileResponse(target, media_type=_guess_content_type(target))
+
+    async def assets_endpoint(request) -> Response:
+        raw = request.path_params["path"]
+        if not os.path.isdir(assets_dir):
+            return await index_endpoint(request)
+        target = _safe_join(assets_dir, raw)
+        if not target or not os.path.isfile(target):
+            return await index_endpoint(request)
+        return FileResponse(target, media_type=_guess_content_type(target))
+
+    async def static_or_index(request) -> Response:
+        raw = request.path_params.get("path", "")
+        target = _safe_join(public_path, raw) if raw else None
+        if target and os.path.isfile(target):
+            return FileResponse(target, media_type=_guess_content_type(target))
+        return await index_endpoint(request)
+
+    routes = [
+        WebSocketRoute("/ws", endpoint=websocket_endpoint),
+        Route(f"{PLUGINS_PREFIX}/{{path:path}}", plugin_assets_endpoint),
+        Route("/assets/{path:path}", assets_endpoint),
+        # catch-all 放最后：不存在的一律回落 index，与 Tornado 行为一致
+        Route("/{path:path}", static_or_index),
+    ]
+    return Starlette(routes=routes, debug=False)
+
+
+class GranianServer:
+    """用 Granian（内嵌模式）承载 Starlette ASGI app 的 Hyperdiv Server。
+
+    内嵌模式在当前进程、当前事件循环中运行，因此无需把应用工厂写成
+    可导入字符串，也没有 Windows spawn 的序列化限制。
+    """
+
+    _instance = None
+
+    def __init__(self, port, app_function, task_runtime, index_page):
+        if GranianServer._instance:
+            raise Exception("Hyperdiv is already running.")
+        GranianServer._instance = self
+        self.port = port
+        self.task_runtime = task_runtime
+        self.app_function = app_function
+        self.index_page = index_page
+        self.asgi_app = build_asgi_app(app_function, task_runtime, index_page)
+        self._server = None
+        self._stopped = threading.Event()
+        self._loop = None
+
+    @property
+    def host(self) -> str:
+        return os.environ.get("HD_HOST", "localhost")
+
+    @property
+    def bind_address(self) -> str:
+        """Granian 需要具体 IP，把 localhost 解析为回环地址。"""
+        host = self.host
+        if host in ("localhost", "127.0.0.1", ""):
+            return "127.0.0.1"
+        return host
+
+    def _make_server(self):
+        from granian.constants import Interfaces
+        from granian.server.embed import Server as EmbeddedServer
+
+        return EmbeddedServer(
+            self.asgi_app,
+            address=self.bind_address,
+            port=self.port,
+            interface=Interfaces.ASGI,
+            websockets=True,
+            log_enabled=True,
+        )
+
+    def listen(self):
+        """构建服务实例；端口在 start() 的事件循环中真正绑定。"""
+        self._server = self._make_server()
+
+    def start(self):
+        print(f"Running at http://{self.host}:{self.port}", file=sys.stderr)
+        print("Ctrl-C to exit", file=sys.stderr)
+        try:
+            asyncio.run(self._run())
+        except KeyboardInterrupt:
+            logger.info("Interrupted.")
+        finally:
+            self.close()
+
+    async def _run(self):
+        self._loop = asyncio.get_running_loop()
+        await self._server.serve()
+
+    def close(self):
+        if self._stopped.is_set():
+            return
+        self._stopped.set()
+        Connection.close_all_connections()
+        GranianServer._instance = None

hyperdiv/cache.py

@@ -0,0 +1,202 @@
+import traceback
+from functools import wraps
+from cachetools.keys import hashkey
+from textwrap import dedent
+from termcolor import colored
+from .frame import AppRunnerFrame
+from .debug import timing
+from .collector import ShadowCollector
+from .component_keys import get_component_key
+from .component_base import Component
+from .exceptions import Stop
+
+
+class Cache:
+    NotFound = object()
+
+    def __init__(self):
+        self.cache = dict()
+
+    def put(self, key, value):
+        self.cache[key] = value
+
+    def get(self, key):
+        if key not in self.cache:
+            return Cache.NotFound
+        return self.cache[key]
+
+    def eject_entries_for_mutated_props(self, mutations):
+        with timing("Cache ejection"):
+            keys_to_eject = set()
+            for key, entry in self.cache.items():
+                deps = entry["deps"]
+                for mutation in mutations:
+                    if mutation in deps:
+                        keys_to_eject.add(key)
+                        break
+            for key_to_eject in keys_to_eject:
+                self.cache.pop(key_to_eject)
+
+
+def cached_wrapper(cache_key, fn, *args, **kwargs):
+    frame = AppRunnerFrame.current()
+
+    cached_value = frame.cache_get(cache_key)
+
+    if cached_value == Cache.NotFound:
+        saved_deps = frame.deps
+        fn_deps = set()
+        frame.deps = fn_deps
+        collector = ShadowCollector()
+        frame.collector_stack.push(collector)
+
+        # Run the function
+        try:
+            result = fn(*args, **kwargs)
+        except Stop:
+            raise
+        except Exception as e:
+            # If the user function raises an error we print a
+            # stacktrace and stop the loop.
+
+            # TODO: Show better stack traces that pertain to the
+            # user's code, and avoid showing the pieces of the stack
+            # trace from inside Hyperdiv, which can be confusing.
+            tb = traceback.extract_tb(e.__traceback__)
+            user_traceback = []
+
+            # hyperdiv_dir = os.path.dirname(source_path)
+
+            for trace in tb:
+                # if not trace.filename.startswith(hyperdiv_dir):
+                user_traceback.append(trace)
+
+            message = (
+                dedent("".join(traceback.format_list(user_traceback)))
+                + f"{e.__class__.__name__}: {e}"
+            )
+
+            print(colored(message, "red"))
+
+            raise Stop()
+
+        if isinstance(result, Component):
+            # TODO: If the function leaks out a component, we
+            # don't want children to be added to it, because those
+            # children would remain in the cached value in
+            # subsequent frames. We could make this more
+            # user-friendly by invalidating the cache when a child
+            # is added.
+            result._sealed = True
+
+        frame.collector_stack.pop()
+        frame.deps = saved_deps
+
+        cached_value = dict(
+            result=result,
+            collector=collector,
+            deps=fn_deps,
+        )
+
+        frame.cache_put(cache_key, cached_value)
+
+    frame.collector_stack.internal_current()._extend(cached_value["collector"])
+    frame.deps.update(cached_value["deps"])
+
+    return cached_value["result"]
+
+
+def cached(fn):
+    """
+    To help improve performance when building large, modular apps,
+    Hyperdiv functions that generate UI components can be wrapped in
+    `@cached` to avoid re-running those function calls if their read
+    dependencies have not changed.
+
+    For example:
+
+    ```py
+    @hd.cached
+    def my_counter(label):
+       state = hd.state(count=0)
+       with hd.box(
+           gap=1,
+           padding=1,
+           border="1px solid neutral-100",
+           border_radius=1,
+       ):
+           hd.markdown(f"### {label}")
+           hd.text(state.count)
+           if hd.button("Increment").clicked:
+               state.count += 1
+
+    my_counter("Counter")
+    my_counter("Counter")
+    ```
+
+    In this example. If we click the `Increment` button in the first
+    counter, that first call to `my_function("Counter")` will re-run,
+    because its read dependency on `button.clicked` is invalidated.
+    But the second call will *not* re-run, since its read dependencies
+    have not changed.
+
+    Similarly, if we click the button in the second counter, the first
+    call to `my_function("Counter")` will not rerun. Instead, the
+    cached UI generated by the previous call to the function will be
+    reused.
+    """
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        call_stack_key = get_component_key()
+        qualname = f"{fn.__module__}.{fn.__name__}"
+        cache_key = (qualname,) + hashkey(call_stack_key, *args, **kwargs)
+
+        return cached_wrapper(cache_key, fn, *args, **kwargs)
+
+    return wrapper
+
+
+def cached_app(app_fn):
+    """
+    Works like @cached but only for the top-level app function. Unlike
+    @cached, it does not use a component key to generate the cache
+    key, enabling the addition of helper functions `is_dirty`, `deps`,
+    and `get_dirty_deps` which help AppRuntime decide when to re-run
+    the user app, as well as print useful debugging info.
+    """
+
+    @wraps(app_fn)
+    def wrapper():
+        return cached_wrapper(make_cache_key(), app_fn)
+
+    def make_cache_key():
+        return f"{app_fn.__module__}.{app_fn.__name__}"
+
+    def get_deps(*args, **kwargs):
+        cached_value = AppRunnerFrame.current().cache_get(make_cache_key())
+        if cached_value == Cache.NotFound:
+            return None
+        return cached_value["deps"]
+
+    def is_dirty(*args, **kwargs):
+        frame = AppRunnerFrame.current()
+        deps = get_deps(*args, **kwargs)
+        if deps is None:
+            return True
+        return frame.deps_are_dirty(deps)
+
+    def get_dirty_deps(*args, **kwargs):
+        frame = AppRunnerFrame.current()
+        deps = get_deps(*args, **kwargs)
+        if deps is None:
+            return None
+        return frame.filter_dirty_deps(deps)
+
+    wrapper.is_dirty = is_dirty
+
+    # Useful for debugging:
+    wrapper.deps = get_deps
+    wrapper.get_dirty_deps = get_dirty_deps
+
+    return wrapper

hyperdiv/cli.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+
+import sys
+import os
+import click
+import shutil
+from importlib.metadata import version
+
+
+def get_version():
+    # Note: This assumes that hyperdiv is installed in the current
+    # virtualenv or distribution. This assumption holds when
+    # developing locally with poetry, because `poetry install`
+    # installs the local project into the virtualenv, using a `.pth`
+    # alias.
+    return version("hyperdiv")
+
+
+@click.group()
+@click.version_option(get_version(), prog_name="Hyperdiv")
+def cli():
+    """Hyperdiv command-line utility."""
+
+
+@cli.command("docs")
+def docs():
+    """Open the Hyperdiv documentation."""
+    docs_app_location = os.path.abspath(
+        os.path.join(
+            os.path.dirname(__file__),
+            "hyperdiv-docs",
+            "start.py",
+        )
+    )
+
+    if not os.path.isfile(docs_app_location):
+        print("ERROR: Cannot find the docs app :(")
+        sys.exit(1)
+
+    python = shutil.which("python3")
+    if not python:
+        python = shutil.which("python")
+
+    if not python:
+        print("ERROR: Cannot find python3 or python")
+        sys.exit(1)
+
+    os.environ["HD_PRODUCTION_LOCAL"] = "1"
+    os.execl(python, "python", docs_app_location)
+
+
+if __name__ == "__main__":
+    cli()

hyperdiv/collector.py

@@ -0,0 +1,64 @@
+class Collector:
+    """
+    The base class that collects the children of Hyperdiv components
+    that can have children.
+
+    Should not be instantiated directly.
+    """
+
+    def __init__(self):
+        self._children = []
+
+    def _collect_child(self, child):
+        self._children.append(child)
+
+    def _extend(self, other_collector):
+        for child in other_collector._children:
+            self._collect_child(child)
+
+
+class ShadowCollector(Collector):
+    pass
+
+
+class CollectorStack:
+    """Collects the UI hierarchy from the application. The 'stack' handles
+    nested containers.
+
+    with box() as b1:   # pushes b1's default slot onto the stack
+      text('a')         # collects into b1
+      with box() as b2: # pushes b2's default slot onto the stack
+        text('b')       # collects into b2
+                        # b2 is popped
+      text('c')         # collects into b1
+                        # b1 is popped
+
+    The top-level of the application is collected into a hidden 'root
+    container'.
+    """
+
+    def __init__(self):
+        self.stack = []
+
+    def push(self, collector):
+        self.stack.append(collector)
+
+    def pop(self):
+        self.stack.pop()
+
+    def current(self):
+        """`current()` is a semi-public interface and can be used by
+        components to introspect the parent component in which they're
+        being collected. It skips ShadowCollectors which are internal
+        collectors used by the cache.
+        """
+        top_index = -1
+        while isinstance(self.stack[top_index], ShadowCollector):
+            top_index -= 1
+        return self.stack[top_index]
+
+    def internal_current(self):
+        return self.stack[-1]
+
+    def collect(self, item):
+        self.internal_current()._collect_child(item)