ex4nicegui 0.9.0__tar.gz → 0.9.2__tar.gz

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ex4nicegui
-Version: 0.9.0
+Version: 0.9.2
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules.
 Author-email: CrystalWindSnake <568166495@qq.com>
 License-Expression: MIT
@@ -8,7 +8,7 @@ License-File: LICENSE
 Keywords: ex4nicegui,gui,nicegui,ui,web,webui
 Requires-Python: >=3.9
 Requires-Dist: executing~=2.0.1
-Requires-Dist: nicegui~=3.0.0
+Requires-Dist: nicegui~=3.5
 Requires-Dist: signe~=0.4.22
 Description-Content-Type: text/markdown
 
@@ -453,6 +453,7 @@ class MyApp(rxui.ViewModel):
       - [tab\_panels](#tab_panels)
       - [lazy\_tab\_panels](#lazy_tab_panels)
       - [scoped\_style](#scoped_style)
+      - [PageState](#pagestate)
     - [BI 模块](#bi-模块)
       - [`bi.data_source`](#bidata_source)
       - [ui\_select](#ui_select)
@@ -1474,6 +1475,56 @@ with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
     ui.label("World")
 ```
 
+---
+
+#### PageState
+
+复杂的页面，可能需要在不同模块的函数中传递状态。`PageState` 类可以更方便管理页面范围的共享状态。
+
+在 state.py 中定义页面状态
+```python
+from ex4nicegui import PageState, to_ref, on
+
+class CounterState(PageState):
+
+    def __init__(self):
+        self.count = to_ref(0)
+
+        @on(self.a)
+        def on_a_change(a):
+            print(f"a changed to {a}")
+
+```
+
+在 view.py 中封装各种视图
+```python
+from ex4nicegui import rxui
+from state import CounterState
+
+def view1():
+    state = CounterState.get()  # 与 view2 函数的状态是共享的 
+    ui.label(f"count: {state.count.value} in view1")
+
+def view2():
+    state = CounterState.get()
+    ui.label(f"count: {state.count.value} in view2")
+
+```
+
+在 `main.py` 中正常导入并调用视图函数即可
+```python
+from ex4nicegui import ui
+from view import view1, view2
+
+@ui.page("/")
+def index():
+    view1()
+    view2()
+
+ui.run()
+
+```
+
 
 ---
 

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/README.md

@@ -439,6 +439,7 @@ class MyApp(rxui.ViewModel):
       - [tab\_panels](#tab_panels)
       - [lazy\_tab\_panels](#lazy_tab_panels)
       - [scoped\_style](#scoped_style)
+      - [PageState](#pagestate)
     - [BI 模块](#bi-模块)
       - [`bi.data_source`](#bidata_source)
       - [ui\_select](#ui_select)
@@ -1460,6 +1461,56 @@ with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
     ui.label("World")
 ```
 
+---
+
+#### PageState
+
+复杂的页面，可能需要在不同模块的函数中传递状态。`PageState` 类可以更方便管理页面范围的共享状态。
+
+在 state.py 中定义页面状态
+```python
+from ex4nicegui import PageState, to_ref, on
+
+class CounterState(PageState):
+
+    def __init__(self):
+        self.count = to_ref(0)
+
+        @on(self.a)
+        def on_a_change(a):
+            print(f"a changed to {a}")
+
+```
+
+在 view.py 中封装各种视图
+```python
+from ex4nicegui import rxui
+from state import CounterState
+
+def view1():
+    state = CounterState.get()  # 与 view2 函数的状态是共享的 
+    ui.label(f"count: {state.count.value} in view1")
+
+def view2():
+    state = CounterState.get()
+    ui.label(f"count: {state.count.value} in view2")
+
+```
+
+在 `main.py` 中正常导入并调用视图函数即可
+```python
+from ex4nicegui import ui
+from view import view1, view2
+
+@ui.page("/")
+def index():
+    view1()
+    view2()
+
+ui.run()
+
+```
+
 
 ---
 

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/__init__.py

@@ -8,8 +8,6 @@ from ex4nicegui.utils.types import (
 )
 from ex4nicegui.utils.scheduler import next_tick
 from ex4nicegui.utils.signals import (
-    effect,
-    effect_refreshable,
     to_raw,
     is_ref,
     to_ref,
@@ -23,9 +21,11 @@ from ex4nicegui.utils.signals import (
     batch,
     is_reactive,
 )
+from ex4nicegui.utils.refreshable import effect, effect_refreshable
 from ex4nicegui.utils.asyncComputed import async_computed
 from ex4nicegui.utils.clientScope import new_scope
 from ex4nicegui.reactive.EChartsComponent.ECharts import reset_echarts_dependencies
+from ex4nicegui.utils.page_state import PageState
 from .version import __version__
 
 __all__ = [
@@ -53,5 +53,6 @@ __all__ = [
     "new_scope",
     "next_tick",
     "reset_echarts_dependencies",
+    "PageState",
     "__version__",
 ]

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/bi/protocols.py

@@ -9,14 +9,11 @@ from ex4nicegui.utils import common as utils_common
 
 
 class IDataSourceAble(Protocol):
-    def get_data(self) -> Any:
-        ...
+    def get_data(self) -> Any: ...
 
-    def reload(self, data) -> None:
-        ...
+    def reload(self, data) -> None: ...
 
-    def apply_filters(self, data, filters: List[_TFilterCallback]) -> Any:
-        ...
+    def apply_filters(self, data, filters: List[_TFilterCallback]) -> Any: ...
 
     def duplicates_column_values(
         self,
@@ -25,30 +22,23 @@ class IDataSourceAble(Protocol):
         *,
         exclude_null_value=True,
         sort_options: Optional[_TDuplicates_column_values_sort_options] = None,
-    ) -> List:
-        ...
+    ) -> List: ...
 
-    def get_aggrid_options(self, data) -> Dict:
-        ...
+    def get_aggrid_options(self, data) -> Dict: ...
 
-    def get_table_options(self, data) -> Dict:
-        ...
+    def get_table_options(self, data) -> Dict: ...
 
-    def slider_check(self, data, column_name: str) -> None:
-        ...
+    def slider_check(self, data, column_name: str) -> None: ...
 
     def slider_min_max(
         self, data, column_name: str
-    ) -> Tuple[Optional[float], Optional[float]]:
-        ...
+    ) -> Tuple[Optional[float], Optional[float]]: ...
 
-    def range_check(self, data, column_name: str) -> None:
-        ...
+    def range_check(self, data, column_name: str) -> None: ...
 
     def range_min_max(
         self, data, column_name: str
-    ) -> Tuple[Optional[float], Optional[float]]:
-        ...
+    ) -> Tuple[Optional[float], Optional[float]]: ...
 
 
 class CallableDataSourceAble(IDataSourceAble):

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/UseDraggable/UseDraggable.py

@@ -125,9 +125,9 @@ class UseDraggable(Element, component="UseDraggable.js"):
         self.on("update", inner_handler, args=_Update_Args)
 
     def apply(self, target: Element):
-        assert (
-            self.__target_id is None
-        ), "draggable can only be applied to one current element"
+        assert self.__target_id is None, (
+            "draggable can only be applied to one current element"
+        )
         self.__target_id = target.id
         self._props["elementId"] = self.__target_id
         # self.run_method("applyTargetId", str(self.__target_id))

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/mermaid/mermaid.py

@@ -19,7 +19,7 @@ class NodeClickEventArguments(UiEventArguments):
 
 class Mermaid(  # type: ignore
     ContentElement,
-    component="mermaid.js",
+    component="ex4ng_mermaid.js",
     dependencies=dependencies,  # type: ignore
 ):
     CONTENT_PROP = "content"

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/mixins/flexLayout.py

@@ -13,11 +13,9 @@ class FlexWrapMixin(Protocol):
     _ui_signal_on: Callable[[Callable[..., Any]], signe.Effect[None]]
 
     @property
-    def element(self) -> ui.element:
-        ...
+    def element(self) -> ui.element: ...
 
-    def bind_style(self, classes) -> Self:
-        ...
+    def bind_style(self, classes) -> Self: ...
 
     def bind_wrap(self, value: TMaybeRef[bool]) -> Self:
         return self.bind_style(
@@ -35,11 +33,9 @@ class FlexAlignItemsMixin(Protocol):
     _ui_signal_on: Callable[[Callable[..., Any]], signe.Effect[None]]
 
     @property
-    def element(self) -> ui.element:
-        ...
+    def element(self) -> ui.element: ...
 
-    def bind_classes(self, classes) -> Self:
-        ...
+    def bind_classes(self, classes) -> Self: ...
 
     def bind_align_items(self, value: TMaybeRef[str]):
         return self.bind_classes(lambda: f"items-{to_value(value)}")

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/mixins/value_element.py

@@ -10,8 +10,7 @@ class ValueElementMixin(Protocol, Generic[T]):
     _ui_signal_on: Callable[[Callable[..., Any]], signe.Effect[None]]
 
     @property
-    def element(self) -> ValueElement:
-        ...
+    def element(self) -> ValueElement: ...
 
     def bind_value(self, value: TMaybeRef[T]):
         @self._ui_signal_on(value)  # type: ignore

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/officials/echarts.py

@@ -140,7 +140,7 @@ class EChartsBindableUi(BindableUi[echarts]):
         const value = {{
             src: '{src}',
             type: '{type}',
-            specialAreas: {json.dumps(special_areas).decode('utf-8')}
+            specialAreas: {json.dumps(special_areas).decode("utf-8")}
         }}
 
         window.ex4ngEchartsMapTasks.set('{map_name}', value);

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/systems/object_system.py

@@ -8,14 +8,12 @@ from typing import (
 
 @runtime_checkable
 class GetItemProtocol(Protocol):
-    def __getitem__(self, key):
-        ...
+    def __getitem__(self, key): ...
 
 
 @runtime_checkable
 class SetItemProtocol(Protocol):
-    def __setitem__(self, key, value):
-        ...
+    def __setitem__(self, key, value): ...
 
 
 def get_attribute(obj: Union[object, GetItemProtocol], name: Union[str, int]) -> Any:

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/reactive/usePagination.py

@@ -17,11 +17,9 @@ def _clamp(value, min_v, max_v) -> int:
 
 
 class _SourceProtocol(Protocol):
-    def __len__(self) -> int:
-        ...
+    def __len__(self) -> int: ...
 
-    def __getitem__(self, __idx: slice) -> Any:
-        ...
+    def __getitem__(self, __idx: slice) -> Any: ...
 
 
 class PaginationRef:

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/utils/apiEffect.py

@@ -52,8 +52,7 @@ def ui_effect(
     debug_trigger: Optional[Callable] = None,
     debug_name: Optional[str] = None,
     scope: Optional[Scope] = None,
-) -> signe.Effect[None]:
-    ...
+) -> signe.Effect[None]: ...
 
 
 def ui_effect(

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/utils/effect.py

@@ -47,8 +47,7 @@ def effect(
     priority_level=1,
     debug_trigger: Optional[Callable] = None,
     debug_name: Optional[str] = None,
-) -> signe.Effect[None]:
-    ...
+) -> signe.Effect[None]: ...
 
 
 def effect(

ex4nicegui-0.9.2/ex4nicegui/utils/page_state.py

@@ -0,0 +1,70 @@
+from typing import ClassVar
+from typing_extensions import Self
+from contextvars import ContextVar
+
+
+class PageState:
+    """
+    A base class for defining per-page reactive state containers.
+
+    Each subclass of `PageState` provides an isolated state context that is automatically
+    managed through a `ContextVar`. When used inside different `ui.page` definitions,
+    each page will maintain its own independent instance of the subclass, ensuring
+    states do not interfere across pages.
+
+    Subclasses should define reactive variables (e.g., created via `to_ref`) within
+    their `__init__` method. The instance can then be accessed anywhere in the same
+    page context using `MyState.get()` — without needing to pass it through function parameters.
+
+    Typical use cases include sharing state across multiple components or functions
+    within the same page.
+
+    @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#PageState
+    @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#PageState
+
+    # Example:
+    .. code-block:: python
+        from ex4nicegui import rxui, to_ref, PageState
+        from nicegui import ui
+
+        class MyState(PageState):
+            def __init__(self):
+                self.a = to_ref(1.0)
+
+        def sub_view():
+            state = MyState.get()
+            rxui.label(lambda: f"{state.a.value=}")
+
+        @ui.page('/')
+        def _():
+            state = MyState.get()
+            rxui.number(value=state.a)
+            sub_view()
+    """
+
+    _ctx: ClassVar[ContextVar["PageState"]]
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls._ctx = ContextVar(f"{cls.__name__}_ctx")
+
+    @classmethod
+    def get(cls) -> Self:
+        """
+        Retrieves the current instance of the page state for this subclass.
+
+        If no instance exists yet in the current context, a new one is created
+        and stored. Subsequent calls within the same page will return the same instance.
+
+        This method allows components and functions within the same page
+        to share reactive state seamlessly without passing references explicitly.
+
+        Returns:
+            Self: The current `PageState` subclass instance associated with this page.
+        """
+        inst = cls._ctx.get(None)
+
+        if inst is None:
+            inst = cls()
+            cls._ctx.set(inst)
+        return inst  # type: ignore

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/utils/refComputed.py

@@ -64,8 +64,7 @@ def ref_computed(
     debug_trigger: Optional[Callable[..., None]] = None,
     priority_level: int = 1,
     debug_name: Optional[str] = None,
-) -> Callable[[Callable[..., T]], ReadonlyRef[T]]:
-    ...
+) -> Callable[[Callable[..., T]], ReadonlyRef[T]]: ...
 
 
 def ref_computed(

ex4nicegui-0.9.2/ex4nicegui/utils/refreshable.py

@@ -0,0 +1,122 @@
+import inspect
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Union,
+    Sequence,
+)
+from nicegui.functions.refreshable import RefreshableContainer
+from ex4nicegui.utils.effect import effect
+from ex4nicegui.utils.types import (
+    _TMaybeRef,
+    TGetterOrReadonlyRef,  # noqa: F401
+)
+from ex4nicegui.utils.refWrapper import RefWrapper  # noqa: F401
+from ex4nicegui.utils.proxy import (
+    to_ref_if_base_type_proxy,
+)
+from ex4nicegui.utils.signals import is_ref, on
+
+_T_effect_refreshable_refs = Union[
+    TGetterOrReadonlyRef,
+    RefWrapper,
+    Sequence[TGetterOrReadonlyRef],
+    _TMaybeRef,
+    Sequence[_TMaybeRef],
+]
+
+
+class effect_refreshable:
+    def __init__(self, fn: Callable, refs: _T_effect_refreshable_refs = []) -> None:
+        self._fn = fn
+
+        refs = to_ref_if_base_type_proxy(refs)
+
+        if isinstance(refs, Sequence):
+            ref_arg = [ref for ref in refs if self._is_valid_ref(ref)]
+        else:
+            ref_arg = [refs] if self._is_valid_ref(refs) else []
+
+        self._refs = ref_arg
+        self()
+
+    @classmethod
+    def _is_valid_ref(cls, ref):
+        return is_ref(ref) or isinstance(ref, Callable)
+
+    @staticmethod
+    def on(refs: _T_effect_refreshable_refs):
+        def warp(
+            fn: Callable,
+        ):
+            if inspect.iscoroutinefunction(fn):
+                return async_effect_refreshable(refs)(fn)
+
+            return effect_refreshable(fn, refs)
+
+        return warp
+
+    def __call__(self, *args: Any, **kwds: Any) -> Any:
+        buffered_view = AsyncBufferedView()
+
+        first = True
+
+        def runner():
+            nonlocal first
+            if first:
+                buffered_view.render(self._fn)
+                first = False
+                return
+
+            buffered_view.render(self._fn)
+
+        if len(self._refs) == 0:
+            runner = effect(runner)
+        else:
+            runner = on(self._refs)(runner)  # type: ignore
+
+        return runner
+
+
+def async_effect_refreshable(source: _T_effect_refreshable_refs):
+    def wrapper(fn: Callable[[], Any]):
+        buffered_view = AsyncBufferedView()
+
+        @on(source, onchanges=False)
+        async def on_source_changed():
+            await buffered_view.async_render(fn)
+
+    return wrapper
+
+
+class AsyncBufferedView:
+    """
+    临时容器做中转，避免异步等待时，页面内容空白的问题
+    """
+
+    def __init__(self):
+        self.viewport = RefreshableContainer()
+        self.staging = RefreshableContainer()
+
+    async def async_render(self, content_creator: Callable[[], Awaitable[Any]]):
+        with self.staging:
+            await content_creator()
+
+        self.viewport.clear()
+
+        for child in list(self.staging):
+            child.move(self.viewport)
+
+        self.staging.clear()
+
+    def render(self, content_creator: Callable[[], Any]):
+        with self.staging:
+            content_creator()
+
+        self.viewport.clear()
+
+        for child in list(self.staging):
+            child.move(self.viewport)
+
+        self.staging.clear()

{ex4nicegui-0.9.0 → ex4nicegui-0.9.2}/ex4nicegui/utils/signals.py

@@ -1,5 +1,4 @@
 from datetime import date, datetime
-import inspect
 import signe
 from signe.core.scope import Scope
 from .clientScope import _CLIENT_SCOPE_MANAGER
@@ -14,19 +13,18 @@ from typing import (
     Union,
     Sequence,
 )
-from nicegui import ui
-from nicegui.functions.refreshable import RefreshableContainer
-from .effect import effect
 from .scheduler import get_uiScheduler
+from .effect import effect  # noqa: F401
 from .types import (
     _TMaybeRef,
     TGetterOrReadonlyRef,
-    Ref,
+    Ref,  # noqa: F401
     TReadonlyRef,  # noqa: F401
     TRef,  # noqa: F401
     DescReadonlyRef,  # noqa: F401
     _TMaybeRef as TMaybeRef,  # noqa: F401
 )
+
 from .refWrapper import RefWrapper, to_ref_wrapper  # noqa: F401
 from .refComputed import ref_computed  # noqa: F401
 from ex4nicegui.utils.proxy import (
@@ -139,88 +137,6 @@ def deep_ref(value: T) -> Ref[T]:
     return to_ref(value, is_deep=True)
 
 
-_T_effect_refreshable_refs = Union[
-    TGetterOrReadonlyRef,
-    RefWrapper,
-    Sequence[TGetterOrReadonlyRef],
-    _TMaybeRef,
-    Sequence[_TMaybeRef],
-]
-
-
-class effect_refreshable:
-    def __init__(self, fn: Callable, refs: _T_effect_refreshable_refs = []) -> None:
-        self._fn = fn
-
-        refs = to_ref_if_base_type_proxy(refs)
-
-        if isinstance(refs, Sequence):
-            ref_arg = [ref for ref in refs if self._is_valid_ref(ref)]
-        else:
-            ref_arg = [refs] if self._is_valid_ref(refs) else []
-
-        self._refs = ref_arg
-        self()
-
-    @classmethod
-    def _is_valid_ref(cls, ref):
-        return is_ref(ref) or isinstance(ref, Callable)
-
-    @staticmethod
-    def on(refs: _T_effect_refreshable_refs):
-        def warp(
-            fn: Callable,
-        ):
-            if inspect.iscoroutinefunction(fn):
-                return async_effect_refreshable(refs)(fn)
-
-            return effect_refreshable(fn, refs)
-
-        return warp
-
-    def __call__(self, *args: Any, **kwds: Any) -> Any:
-        re_func = ui.refreshable(self._fn)
-
-        first = True
-
-        def runner():
-            nonlocal first
-            if first:
-                re_func()
-                first = False
-                return
-
-            re_func.refresh()
-
-        if len(self._refs) == 0:
-            runner = effect(runner)
-        else:
-            runner = on(self._refs)(runner)  # type: ignore
-
-        return runner
-
-
-def async_effect_refreshable(source: _T_effect_refreshable_refs):
-    def wrapper(fn: Callable[[], Any]):
-        @on(source, onchanges=False)
-        async def on_source_changed():
-            with temp_box:
-                await fn()
-
-            container.clear()
-
-            for child in list(temp_box):
-                child.move(container)
-
-            temp_box.clear()
-
-        # 临时容器做中转，避免异步等待时，页面内容空白的问题
-        temp_box = RefreshableContainer()
-        container = RefreshableContainer()
-
-    return wrapper
-
-
 def on(
     refs: Union[TGetterOrReadonlyRef, RefWrapper, Sequence[TGetterOrReadonlyRef], Any],
     onchanges=False,