hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/tests/server_tests.py

@@ -0,0 +1,103 @@
+import os
+import json
+import signal
+import multiprocessing
+import requests
+import websocket
+import hyperdiv as hd
+from ..main import wait_for_port
+
+
+def empty_app():
+    def main():
+        pass
+
+    hd.run(main)
+
+
+class MockServer:
+    def __init__(self, fn=empty_app, port=9070):
+        self.fn = fn
+        self.port = port
+        self.process = None
+        self.prev_port = os.environ.get("HD_PORT")
+        self.prev_debug = os.environ.get("HD_DEBUG")
+
+    def __enter__(self):
+        os.environ["HD_PORT"] = str(self.port)
+        os.environ["HD_DEBUG"] = "1"
+        self.process = multiprocessing.Process(target=self.fn)
+        self.process.start()
+        wait_for_port(self.port)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        os.kill(self.process.pid, signal.SIGINT)
+        self.process.join()
+
+        if self.prev_port is None:
+            del os.environ["HD_PORT"]
+        else:
+            os.environ["HD_PORT"] = self.prev_port
+
+        if self.prev_debug is None:
+            del os.environ["HD_DEBUG"]
+        else:
+            os.environ["HD_DEBUG"] = self.prev_debug
+
+    def open_websocket(self):
+        return websocket.create_connection(f"ws://{os.environ.get('HD_HOST', 'localhost')}:{self.port}/ws")
+
+    def request_path(self, path):
+        return requests.get(f"http://{os.environ.get('HD_HOST', 'localhost')}:{self.port}{path}").text
+
+
+def checkbox_app():
+    def my_fun():
+        b = hd.checkbox("Hello", key="my-checkbox")
+
+        if b.checked:
+            hd.text("checked")
+
+    hd.run(my_fun)
+
+
+def test_websocket():
+    """TODO"""
+
+    with MockServer(checkbox_app) as s:
+        ws = s.open_websocket()
+        dom = json.loads(ws.recv())
+        root = dom["dom"]
+        root_key = root["key"]
+        assert len(root["children"]) == 1
+        assert root["children"][0]["key"] == "my-checkbox"
+
+        ws.send(
+            json.dumps(
+                [{"type": "update", "updates": [["my-checkbox", "checked", True]]}]
+            )
+        )
+        response = json.loads(ws.recv())
+        assert "diff" in response
+        assert root_key in response["diff"]
+        assert "children" in response["diff"][root_key]
+        assert len(response["diff"][root_key]["children"]) == 1
+        cmd = response["diff"][root_key]["children"][0]
+        assert cmd[0] == "insert"
+        assert cmd[1] == 1
+        assert len(cmd[2]) == 1
+        txt = cmd[2][0]
+        assert txt["props"] == {"content": "checked"}
+        ws.close()
+
+
+def test_server():
+    with MockServer() as s:
+        t1 = s.request_path("/")
+        t2 = s.request_path("/foo")
+        t3 = s.request_path("/foo/bar")
+
+        assert t1 == t2 == t3
+
+        s.request_path("/build/bundle.js")

hyperdiv/tests/sqlite_tests.py

@@ -0,0 +1,80 @@
+import pytest
+import os
+import tempfile
+from ..sqlite import sql, sqlite, sqlite_tx, retry, migrate
+
+
+@retry
+def insert_user_1(db_path, name, age):
+    with sqlite(db_path) as (_, cursor):
+        cursor.execute("insert into Users (name, age) values (?, ?)", (name, age))
+
+
+@retry
+def insert_user_2(db_path, name, age, role):
+    with sqlite_tx(db_path) as (_, cursor):
+        cursor.execute(
+            "insert into Users (name, age, role) values (?, ?, ?)", (name, age, role)
+        )
+
+
+@retry
+def select_users_1(db_path):
+    with sqlite(db_path) as (_, cursor):
+        cursor.execute("select name, age from Users")
+        return cursor.fetchall()
+
+
+@retry
+def select_users_2(db_path):
+    with sqlite_tx(db_path) as (_, cursor):
+        cursor.execute("select name, age, role from Users")
+        return cursor.fetchall()
+
+
+@retry
+def failed_insert_user_2(db_path, name, age, role):
+    with sqlite_tx(db_path) as (_, cursor):
+        cursor.execute(
+            "insert into Users (name, age, role) values (?, ?, ?)", (name, age, role)
+        )
+        raise Exception("Failure")
+
+
+def test_sqlite():
+    with tempfile.NamedTemporaryFile(delete=False) as f:
+        db_path = f.name
+
+    migrations = [sql("create table Users (name, age)")]
+
+    migrate(db_path, migrations)
+    # Migrating again does nothing
+    migrate(db_path, migrations)
+
+    insert_user_1(db_path, "Steve", 40)
+    insert_user_1(db_path, "Andy", 32)
+
+    users = select_users_1(db_path)
+    assert users == [{"name": "Steve", "age": 40}, {"name": "Andy", "age": 32}]
+
+    migrations += [sql("alter table Users add column role")]
+    migrate(db_path, migrations)
+
+    insert_user_2(db_path, "Mary", 23, "Manager")
+    insert_user_2(db_path, "Joe", 38, "Engineer")
+
+    users = select_users_2(db_path)
+    assert users == [
+        {"name": "Steve", "age": 40, "role": None},
+        {"name": "Andy", "age": 32, "role": None},
+        {"name": "Mary", "age": 23, "role": "Manager"},
+        {"name": "Joe", "age": 38, "role": "Engineer"},
+    ]
+
+    with pytest.raises(Exception):
+        failed_insert_user_2(db_path, "Jimmy", 50, "Manager")
+
+    # The inserted record got rolled back
+    assert select_users_2(db_path) == users
+
+    os.remove(db_path)

hyperdiv/tests/style_part_tests.py

@@ -0,0 +1,54 @@
+import pytest
+from ..test_utils import mock_frame
+from ..components.style import style
+from ..components.button import button
+from ..style_part import StylePart
+
+
+@mock_frame
+def test_style_part():
+    # None case
+    b = button(label_style=None)
+    assert b.label_style is None
+
+    # Non-style case
+    with pytest.raises(Exception):
+        button(label_style=10)
+
+    # Basic case, does not add `display:flex` or direction.
+    b = button(label_style=style(width=10))
+
+    rendered = b.render()
+    assert rendered["style"][f"#{b._key}::part(label)"] == "width:10rem"
+
+    # Test that 'display:flex' and 'direction' are automatically added:
+    b = button(label_style=style(width=10, align="center"))
+
+    rendered = b.render()
+
+    style_items = set(rendered["style"][f"#{b._key}::part(label)"].split(";"))
+
+    assert style_items == set(
+        [
+            "display:flex",
+            "width:10rem",
+            "align-items:center",
+            "flex-direction:column",
+        ]
+    )
+
+    # Test that direction is correctly taken into account:
+    b = button(label_style=style(width=10, align="center", direction="horizontal"))
+
+    rendered = b.render()
+
+    style_items = set(rendered["style"][f"#{b._key}::part(label)"].split(";"))
+
+    assert style_items == set(
+        [
+            "display:flex",
+            "width:10rem",
+            "align-items:center",
+            "flex-direction:row",
+        ]
+    )

hyperdiv/ui_command.py

@@ -0,0 +1,108 @@
+from .frame import AppRunnerFrame
+from .components.async_command import async_command
+
+
+class UICommand:
+    """
+    Just an in-memory representation of a command. `result_key` is the
+    Hyperdiv key of the `async_command` object returned by the
+    command. The UI will update the done/running/result props at this
+    key when the command is done executing.
+    """
+
+    def __init__(self, result_key, target, command, args):
+        self.result_key = result_key
+        self.target = target
+        self.command = command
+        self.args = args
+
+    def render(self):
+        return dict(
+            resultKey=self.result_key,
+            target=self.target,
+            command=self.command,
+            args=self.args,
+        )
+
+    @staticmethod
+    def send(result_key, target, command, args):
+        """Sends a command to the UI at the end of the current frame."""
+        AppRunnerFrame.current().add_command(
+            UICommand(result_key, target, command, args)
+        )
+
+
+def ui_read(target, command, args):
+    """Invoke a UI read command. A read will send the command to the UI
+    and return a result object in `running` state. Calling this read
+    again on subsequent frames will *not* re-send the read call to the
+    UI. It will remain in `done` state and return the same value over
+    and over.
+
+    To trigger a re-read, you can call `clear()` on the returned
+    `async_command` object, which resets the running/done props and causes
+    the read to be sent again on the next frame.
+    """
+
+    result = async_command()
+
+    sent = False
+
+    if not result.running and not result.done:
+        UICommand.send(result._key, target, command, args)
+        result.running = True
+        sent = True
+
+    return result, sent
+
+
+def ui_write(target, command, args):
+    """Invoke a UI write command. Unlike a read, a write call will send
+    the command to the UI on every call. Intuitively, writes should
+    not be called on every frame, but rather only in response to
+    events like `clicked`.
+
+    Writes still return a `async_command` object that can be inspected to
+    determine the status of the write. However, note that if you
+    immediately invoke the same write again, before the previous has
+    finished, the `async_command` object will likely be updated by the 1st
+    (unfinished) call, and then again by the 2nd.
+    """
+    result = async_command()
+    result.clear()
+
+    UICommand.send(result._key, target, command, args)
+
+    result.running = True
+
+    return result
+
+
+class UICommandCache:
+    """
+    A generic cache that stores UI command objects in Hyperdiv
+    session storage.
+    """
+
+    def __init__(self, storage_key):
+        self.storage_key = storage_key
+
+    def cache_result(self, key, result):
+        storage = AppRunnerFrame.current().get_storage(self.storage_key)
+
+        storage.setdefault(key, [])
+        storage[key].append(result)
+
+    def clear_cache_at_key(self, key):
+        storage = AppRunnerFrame.current().get_storage(self.storage_key)
+
+        read_results = storage.get(key, [])
+        for read_result in read_results:
+            read_result.clear()
+
+    def clear_cache(self):
+        storage = AppRunnerFrame.current().get_storage(self.storage_key)
+
+        for read_results in storage.values():
+            for read_result in read_results:
+                read_result.clear()

hyperdiv/ui_prop_state.py

@@ -0,0 +1,92 @@
+from .component_base import Component
+from .diff import Insert
+
+
+class UIPropState:
+    """Holds the prop values that the browser holds at this moment. This is
+    used to determine if a prop changed and the new value should be
+    sent to the browser.
+
+    This data structure is updated
+
+    (a) When a new dom or dom diff is sent to the browser. The data
+        structure is updated to hold those new prop values before the
+        dom or diff are sent off.
+
+    (b) When a prop change is received from the browser. For example
+        when the user checks a checkbox and `checked` is updated to
+        `True`, this prop state is updated also.
+
+    Note that (b) implicitly prevents browser-modified values from
+    being echoed back to the browser.
+    """
+
+    Unset = object()
+
+    def __init__(self, state):
+        # A reference to component global state
+        self.state = state
+        # The values of props held by the UI
+        self.props = dict()
+
+    def get_prop_value(self, key, prop_name):
+        if key not in self.props:
+            return UIPropState.Unset
+        if prop_name not in self.props[key]:
+            return UIPropState.Unset
+        return self.props[key][prop_name]
+
+    def set_prop_values(self, props):
+        for prop in props:
+            if prop.internal:
+                continue
+            if isinstance(prop.value, Component):
+                self.set_prop_values_from_component(prop.value)
+            else:
+                self.set_prop_value(prop)
+
+    def set_prop_value(self, prop):
+        if prop.internal:
+            return
+        if prop.key not in self.props:
+            self.props[prop.key] = dict()
+        self.props[prop.key][prop.name] = prop.value
+
+    def set_prop_values_from_component(self, component):
+        key = component._key
+        props = self.state.get_props(key).values()
+        self.set_prop_values(props)
+        if component._has_children:
+            for child in component._children:
+                self.set_prop_values_from_component(child)
+
+    def set_prop_values_from_diff(self, diff):
+        for component_diff in diff._diff:
+            self.set_prop_values(component_diff.props)
+            for command in component_diff.children:
+                if isinstance(command, Insert):
+                    for component in command.components:
+                        self.set_prop_values_from_component(component)
+
+    def prop_changed(self, prop):
+        if isinstance(prop.value, Component):
+            return self.component_changed(prop.value)
+
+        if prop.internal:
+            return False
+
+        ui_prop_value = self.get_prop_value(prop.key, prop.name)
+
+        if ui_prop_value == UIPropState.Unset:
+            return True
+
+        return ui_prop_value != prop.value
+
+    def component_changed(self, component):
+        props = self.state.get_props(component._key)
+
+        for prop in props.values():
+            if self.prop_changed(prop):
+                return True
+
+        return False

hyperdiv/ui_singleton.py

@@ -0,0 +1,70 @@
+from .component_base import BaseState
+
+
+class SingletonCollector(type):
+    """
+    Collects Singleton and BrowserSingleton classes as they are defined. The
+    singleton classes have to be instantiated in bulk by `AppRunner`,
+    and this class provides the mechanism that collects all the
+    singletons in one place.
+
+    BrowserSingletons are singletons that are sent to the browser, like
+    `location` and `theme`. Singletons stay on the backend and don't
+    have a browser counterpart.
+    """
+
+    ui_singleton_classes: set[type] = set()
+    singleton_classes: set[type] = set()
+
+    def __new__(cls, clsname, bases, attrs):
+        klass = super().__new__(cls, clsname, bases, attrs)
+        if clsname not in ("BrowserSingleton", "Singleton"):
+            if issubclass(klass, Singleton):
+                SingletonCollector.singleton_classes.add(klass)
+            elif issubclass(klass, BrowserSingleton):
+                SingletonCollector.ui_singleton_classes.add(klass)
+        return klass
+
+    @staticmethod
+    def create_ui_singletons():
+        return [
+            component_class()
+            for component_class in SingletonCollector.ui_singleton_classes
+        ]
+
+    @staticmethod
+    def create_singletons():
+        return [
+            component_class()
+            for component_class in SingletonCollector.ui_singleton_classes.union(
+                SingletonCollector.singleton_classes
+            )
+        ]
+
+
+class BrowserSingleton(BaseState, metaclass=SingletonCollector):
+    """
+    A browser singleton is a non-UI component that communicates values
+    between Python <-> browser.
+
+    All instances of a BrowserSingleton class share the same underlying
+    state.
+    """
+
+    def __init__(self):
+        """BrowserSingleton should not be instantiated directly."""
+        super().__init__()
+
+
+class Singleton(BaseState, metaclass=SingletonCollector):
+    """
+    A Singleton is a non-UI component that never gets sent to the
+    frontend. It is backend-only.
+
+    All instances of a Singleton class share the same underlying
+    state.
+    """
+
+    def __init__(self):
+        """Singleton should not be instantiated directly."""
+        super().__init__()

hyperdivlite-0.1.9.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: hyperdivlite
+Version: 0.1.9
+Summary: A lightweight Hyperdiv fork with Granian as the default backend and optional Tornado
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: hyperdiv,reactive,ui,web,framework,granian,asgi
+Author: Marius Nita
+Author-email: m@mariusnita.com
+Requires-Python: >=3.10,<4.0
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Provides-Extra: tornado
+Requires-Dist: Jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: cachetools (>=5.3.0,<6.0.0)
+Requires-Dist: click (>=8.1.3,<9.0.0)
+Requires-Dist: email-validator (>=2.0.0,<3.0.0)
+Requires-Dist: frozendict (>=2.3.10,<3.0.0)
+Requires-Dist: granian (>=2.8,<3.0)
+Requires-Dist: mistune (>=2.0.5,<3.0.0)
+Requires-Dist: parse (>=1.20.0,<2.0.0)
+Requires-Dist: pygments (>=2.17.2,<3.0.0)
+Requires-Dist: starlette (>=0.46)
+Requires-Dist: termcolor (>=2.3.0,<3.0.0)
+Requires-Dist: tornado (>=6.5,<7.0) ; extra == "tornado"
+Requires-Dist: xxhash (>=3.0.0,<4.0.0)
+Description-Content-Type: text/markdown
+
+# HyperdivLite
+
+**HyperdivLite** 是 [Hyperdiv](https://hyperdiv.io) 的轻量分支（fork），保留了原来的
+即时模式响应式 UI 编程模型，同时把服务器传输层换成 **Granian + Starlette**。
+
+核心变化只有一处：**默认后端改为 Granian，Tornado 变为可选依赖**。
+组件系统、渲染管线、状态管理、任务运行时与上游保持一致。
+
+## 与上游的差异
+
+| 项目 | Hyperdiv 0.1.9 | HyperdivLite |
+|------|----------------|--------------|
+| 默认服务器 | Tornado | Granian（内嵌模式） |
+| Tornado 依赖 | 核心依赖，必装 | 可选 extra，默认不装 |
+| ASGI 层 | Tornado WebSocket | Starlette ASGI |
+| 启动参数 | 无 | 无，`hd.run()` 直接可用 |
+| Windows 支持 | 可用 | 可用，无 spawn 序列化问题 |
+| 后端切换 | 不可切换 | `HD_SERVER=granian` / `HD_SERVER=tornado` |
+
+## 安装
+
+```bash
+# 默认安装：Granian + Starlette，不含 Tornado
+pip install hyperdivlite
+
+# 需要兼容旧的 Tornado 后端时
+pip install "hyperdivlite[tornado]"
+```
+
+Python 版本要求：3.10 及以上。
+
+> 注意：安装后的 **导入名仍然是 `hyperdiv`**，因此代码里写 `import hyperdiv as hd`
+> 无需改动，与上游保持兼容。
+
+## 快速开始
+
+```python
+import hyperdiv as hd
+
+
+def main():
+    state = hd.state(count=0)
+
+    with hd.box(padding=2, gap=1):
+        hd.text(f"当前计数：{state.count}")
+        if hd.button("加一").clicked:
+            state.count += 1
+
+
+if __name__ == "__main__":
+    hd.run(main)
+```
+
+```bash
+python app.py
+```
+
+默认监听 `http://localhost:8988`，可用 `HD_PORT` 指定端口、`HD_HOST` 指定地址。
+
+## 后端选择
+
+不设置任何环境变量时使用 Granian。需要旧后端时显式切换：
+
+```bash
+# 默认：Granian
+python app.py
+
+# 使用 Tornado（需先安装 hyperdivlite[tornado]）
+HD_SERVER=tornado python app.py
+```
+
+选择顺序：
+
+1. `HD_SERVER=tornado` → Tornado
+2. `HD_SERVER=granian` → Granian
+3. 未设置 → Granian
+4. Granian 不可用但 Tornado 已装 → 自动回退 Tornado
+5. 都不可用 → 明确报错
+
+## 功能特性
+
+- 即时模式 UI：组件调用即渲染，无需手写模板
+- 隐式响应式状态：状态变更自动触发重渲染
+- 内置 Shoelace 组件库，支持亮色/暗色主题
+- Chart.js 图表、Markdown 渲染、表单校验
+- WebSocket 虚拟 DOM 增量补丁
+- 插件系统与自定义组件
+- 静态资源兜底：任意有效路径回落 `index`，支持前端路由
+
+## 文档应用
+
+安装后可本地打开上游文档：
+
+```bash
+hyperdiv docs
+```
+
+## 架构说明
+
+后端适配层位于 `hyperdiv/backends/`，只实现两个契约：
+
+1. `Server(port, app_function, task_runtime, index_page)`
+2. 连接对象提供 `send(message: dict)`
+
+因此 `app_runner.py`、组件系统、渲染与差异计算完全不需要改动。
+详细设计见 [BACKENDS.md](BACKENDS.md)。
+
+## 验证
+
+`examples/` 下提供两个验证脚本：
+
+```bash
+python examples/check_ws.py <port>       # WebSocket 首帧 DOM
+python examples/check_click.py <port>    # 端到端点击交互
+```
+
+已实测：默认 Granian 与可选 Tornado 两种后端下，首页、静态资源、路径回退、
+WebSocket 首帧、点击交互、进程退出均正常。
+
+## 许可
+
+沿袭上游 Apache-2.0 许可证，原始版权归 Marius Nita 及 Hyperdiv 贡献者所有。
+