ex4nicegui 0.6.7__py3-none-any.whl → 0.6.9__py3-none-any.whl

ex4nicegui/utils/refComputed.py

@@ -0,0 +1,147 @@
+from functools import partial
+import types
+import signe
+from .clientScope import _CLIENT_SCOPE_MANAGER
+from typing import (
+    Any,
+    Dict,
+    Protocol,
+    Type,
+    TypeVar,
+    Generic,
+    overload,
+    Optional,
+    Callable,
+    cast,
+    Union,
+)
+from .scheduler import get_uiScheduler
+from .types import (
+    ReadonlyRef,
+    DescReadonlyRef,
+)
+
+
+T = TypeVar("T", covariant=True)
+
+
+class TInstanceCall(Protocol[T]):
+    def __call__(_, self) -> T:  # type: ignore
+        ...
+
+
+@overload
+def ref_computed(
+    fn: Union[Callable[[], T], TInstanceCall[T]],
+    *,
+    desc="",
+    debug_trigger: Optional[Callable[..., None]] = None,
+    priority_level: int = 1,
+    debug_name: Optional[str] = None,
+) -> ReadonlyRef[T]:
+    """Takes a getter function and returns a readonly reactive ref object for the returned value from the getter. It can also take an object with get and set functions to create a writable ref object.
+
+    @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#ref_computed
+    @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#ref_computed
+
+
+    Args:
+        fn (Callable[[], T]): _description_
+        desc (str, optional): _description_. Defaults to "".
+        debug_trigger (Optional[Callable[..., None]], optional): _description_. Defaults to None.
+        priority_level (int, optional): _description_. Defaults to 1.
+        debug_name (Optional[str], optional): _description_. Defaults to None.
+
+    """
+    ...
+
+
+@overload
+def ref_computed(
+    fn=None,
+    *,
+    desc="",
+    debug_trigger: Optional[Callable[..., None]] = None,
+    priority_level: int = 1,
+    debug_name: Optional[str] = None,
+) -> Callable[[Callable[..., T]], ReadonlyRef[T]]:
+    ...
+
+
+def ref_computed(
+    fn: Optional[Union[Callable[[], T], TInstanceCall[T]]] = None,
+    *,
+    desc="",
+    debug_trigger: Optional[Callable[..., None]] = None,
+    priority_level: int = 1,
+    debug_name: Optional[str] = None,
+) -> Union[ReadonlyRef[T], Callable[[Callable[..., T]], ReadonlyRef[T]]]:
+    kws = {
+        "debug_trigger": debug_trigger,
+        "priority_level": priority_level,
+        "debug_name": debug_name,
+    }
+
+    if fn:
+        if _helpers.is_class_define_method(fn):
+            return cast(
+                ref_computed_method[T],
+                ref_computed_method(fn, computed_args=kws),  # type: ignore
+            )  # type: ignore
+
+        getter = signe.Computed(
+            cast(Callable[[], T], fn),
+            **kws,
+            scope=_CLIENT_SCOPE_MANAGER.get_current_scope(),
+            scheduler=get_uiScheduler(),
+        )
+        return cast(DescReadonlyRef[T], getter)
+
+    else:
+
+        def wrap(fn: Callable[[], T]):
+            return ref_computed(fn, **kws)
+
+        return wrap
+
+
+class ref_computed_method(Generic[T]):
+    __isabstractmethod__: bool
+
+    def __init__(self, fget: Callable[[Any], T], computed_args: Dict) -> None:
+        self._fget = fget
+        self._computed_args = computed_args
+
+    def __set_name__(self, owner, name):
+        _helpers.add_computed_to_instance(owner, name, self._fget, self._computed_args)
+
+
+class _helpers:
+    @staticmethod
+    def is_class_define_method(fn: Callable):
+        has_name = hasattr(fn, "__name__")
+        qualname_prefix = f".<locals>.{fn.__name__}" if has_name else ""
+
+        return (
+            hasattr(fn, "__qualname__")
+            and has_name
+            and "." in fn.__qualname__
+            and qualname_prefix != fn.__qualname__[-len(qualname_prefix) :]
+            and (isinstance(fn, types.FunctionType))
+        )
+
+    @staticmethod
+    def add_computed_to_instance(
+        cls_type: Type, attr_name: str, fn: Callable, computed_args: Dict
+    ):
+        """
+        Add an attribute to an instance of a class.
+        """
+        original_init = cls_type.__init__
+
+        def new_init(self, *args, **kwargs):
+            original_init(self, *args, **kwargs)
+            setattr(self, attr_name, ref_computed(partial(fn, self), **computed_args))
+
+        cls_type.__init__ = new_init
+        return cls_type

ex4nicegui/utils/refWrapper.py

@@ -0,0 +1,57 @@
+import signe
+from typing import (
+    TypeVar,
+    Generic,
+    Optional,
+    Callable,
+    cast,
+)
+import warnings
+from .types import (
+    TGetterOrReadonlyRef,
+)
+
+T = TypeVar("T")
+
+
+class RefWrapper(Generic[T]):
+    __slot__ = ("_getter_fn", "_setter_fn", "")
+
+    def __init__(
+        self,
+        getter_or_ref: TGetterOrReadonlyRef[T],
+        setter_or_ref: Optional[Callable[[T], None]] = None,
+    ):
+        if signe.is_signal(getter_or_ref):
+            self._getter_fn = lambda: getter_or_ref.value
+
+            def ref_setter(v):
+                getter_or_ref.value = v  # type: ignore
+
+            self._setter_fn = ref_setter
+        elif isinstance(getter_or_ref, Callable):
+            self._getter_fn = getter_or_ref
+            self._setter_fn = setter_or_ref or (lambda x: None)
+        else:
+            self._getter_fn = lambda: getter_or_ref
+            self._setter_fn = lambda x: None
+
+        self._is_readonly = False
+
+    @property
+    def value(self) -> T:
+        return cast(T, self._getter_fn())
+
+    @value.setter
+    def value(self, new_value: T):
+        if self._is_readonly:
+            warnings.warn("readonly ref cannot be assigned.")
+            return
+        return self._setter_fn(new_value)
+
+
+def to_ref_wrapper(
+    getter_or_ref: TGetterOrReadonlyRef[T],
+    setter_or_ref: Optional[Callable[[T], None]] = None,
+):
+    return RefWrapper(getter_or_ref, setter_or_ref)

ex4nicegui/utils/scheduler.py

@@ -1,15 +1,13 @@
 from collections import deque
 import signe
-from typing import (
-    TypeVar,
-    Callable,
-)
+from typing import TypeVar, Callable, Literal
 from functools import lru_cache
 
 
 T = TypeVar("T")
 
 T_JOB_FN = Callable[[], None]
+T_JOB_TYPE = Literal["pre", "post"]
 
 
 class UiScheduler(signe.ExecutionScheduler):
@@ -18,6 +16,7 @@ class UiScheduler(signe.ExecutionScheduler):
 
         self._pre_deque: deque[T_JOB_FN] = deque()
         self._post_deque: deque[T_JOB_FN] = deque()
+        self._next_tick_deque: deque[T_JOB_FN] = deque()
 
     def pre_job(self, job: T_JOB_FN):
         self._pre_deque.appendleft(job)
@@ -25,6 +24,9 @@ class UiScheduler(signe.ExecutionScheduler):
     def post_job(self, job: T_JOB_FN):
         self._post_deque.appendleft(job)
 
+    def next_tick_job(self, job: T_JOB_FN):
+        self._next_tick_deque.appendleft(job)
+
     def run(self):
         while self._scheduler_fns:
             super().run()
@@ -33,6 +35,7 @@ class UiScheduler(signe.ExecutionScheduler):
             try:
                 self.run_pre_deque()
                 self.run_post_deque()
+                self.run_next_tick_deque()
                 pass
             except Exception as e:
                 raise e
@@ -47,7 +50,20 @@ class UiScheduler(signe.ExecutionScheduler):
         while self._post_deque:
             self._post_deque.pop()()
 
+    def run_next_tick_deque(self):
+        while self._next_tick_deque:
+            self._next_tick_deque.pop()()
+
 
 @lru_cache(maxsize=1)
 def get_uiScheduler():
     return UiScheduler()
+
+
+def next_tick(job: T_JOB_FN):
+    """Schedule a job to run on the next tick of the event loop.
+
+    Args:
+        job (T_JOB_FN):  The job to run on the next tick.
+    """
+    get_uiScheduler().next_tick_job(job)

ex4nicegui/utils/signals.py

@@ -1,17 +1,11 @@
 from datetime import date, datetime
-from functools import partial
-import types
-from weakref import WeakValueDictionary
 import signe
-from signe.core.protocols import ComputedResultProtocol
+from signe.core.scope import Scope
 from .clientScope import _CLIENT_SCOPE_MANAGER
 from typing import (
     Any,
     Dict,
-    Protocol,
     TypeVar,
-    Generic,
-    overload,
     Optional,
     Callable,
     cast,
@@ -21,85 +15,51 @@ from typing import (
 from nicegui import ui
 from .effect import effect
 from .scheduler import get_uiScheduler
-import warnings
+from .types import (
+    _TMaybeRef,
+    TGetterOrReadonlyRef,
+    Ref,
+    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
 
 T = TypeVar("T")
 
 
-TReadonlyRef = ComputedResultProtocol[T]
-ReadonlyRef = TReadonlyRef[T]
-DescReadonlyRef = TReadonlyRef[T]
-
-TGetterOrReadonlyRef = signe.TGetter[T]
-
-
 is_reactive = signe.is_reactive
+to_raw = signe.to_raw
 
 
 def reactive(obj: T) -> T:
     return signe.reactive(obj, get_uiScheduler())
 
 
-class RefWrapper(Generic[T]):
-    __slot__ = ("_getter_fn", "_setter_fn", "")
-
-    def __init__(
-        self,
-        getter_or_ref: TGetterOrReadonlyRef[T],
-        setter_or_ref: Optional[Callable[[T], None]] = None,
-    ):
-        if signe.is_signal(getter_or_ref):
-            self._getter_fn = lambda: getter_or_ref.value
-
-            def ref_setter(v):
-                getter_or_ref.value = v  # type: ignore
-
-            self._setter_fn = ref_setter
-        elif isinstance(getter_or_ref, Callable):
-            self._getter_fn = getter_or_ref
-            self._setter_fn = setter_or_ref or (lambda x: None)
-        else:
-            self._getter_fn = lambda: getter_or_ref
-            self._setter_fn = lambda x: None
-
-        self._is_readonly = False
-
-    @property
-    def value(self) -> T:
-        return cast(T, self._getter_fn())
-
-    @value.setter
-    def value(self, new_value: T):
-        if self._is_readonly:
-            warnings.warn("readonly ref cannot be assigned.")
-            return
-        return self._setter_fn(new_value)
-
-
-def to_ref_wrapper(
-    getter_or_ref: TGetterOrReadonlyRef[T],
-    setter_or_ref: Optional[Callable[[T], None]] = None,
-):
-    return RefWrapper(getter_or_ref, setter_or_ref)
-
-
-_TMaybeRef = signe.TMaybeSignal[T]
-TRef = signe.TSignal[T]
-Ref = TRef[T]
-
-
-to_raw = signe.to_raw
-
-
 def is_setter_ref(obj):
     return isinstance(obj, (signe.Signal, RefWrapper))
 
 
-def is_ref(obj):
+def is_ref(obj: Any):
+    """Checks if a value is a ref object."""
     return signe.is_signal(obj) or isinstance(obj, (RefWrapper))
 
 
 def to_value(obj: Union[_TMaybeRef[T], RefWrapper]) -> T:
+    """unwraps a ref object and returns its inner value.
+
+    Args:
+        obj (Union[_TMaybeRef[T], RefWrapper]): A getter function, an existing ref, or a non-function value.
+
+    ## Example
+    ```python
+    to_value(1)  # 1
+    to_value(lambda: 1)  # 1
+    to_value(to_ref(1))  # 1
+    ```
+    """
     if is_ref(obj):
         return obj.value  # type: ignore
     if isinstance(obj, Callable):
@@ -144,7 +104,7 @@ def _ref_comp_with_None(old, new):
     return False
 
 
-def ref(value: T, is_deep=False):
+def ref(value: T, is_deep=False) -> Ref[T]:
     comp = False  # Default never equal
 
     if _is_comp_values(value):
@@ -170,135 +130,33 @@ def deep_ref(value: T) -> Ref[T]:
     return to_ref(value, is_deep=True)
 
 
-class TInstanceCall(Protocol[T]):
-    def __call__(_, self) -> T:
-        ...
-
-
-@overload
-def ref_computed(
-    fn: Union[Callable[[], T], TInstanceCall[T]],
-    *,
-    desc="",
-    debug_trigger: Optional[Callable[..., None]] = None,
-    priority_level: int = 1,
-    debug_name: Optional[str] = None,
-) -> ReadonlyRef[T]:
-    """Takes a getter function and returns a readonly reactive ref object for the returned value from the getter. It can also take an object with get and set functions to create a writable ref object.
-
-    @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#ref_computed
-    @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#ref_computed
-
-
-    Args:
-        fn (Callable[[], T]): _description_
-        desc (str, optional): _description_. Defaults to "".
-        debug_trigger (Optional[Callable[..., None]], optional): _description_. Defaults to None.
-        priority_level (int, optional): _description_. Defaults to 1.
-        debug_name (Optional[str], optional): _description_. Defaults to None.
-
-    """
-    ...
-
-
-@overload
-def ref_computed(
-    fn=None,
-    *,
-    desc="",
-    debug_trigger: Optional[Callable[..., None]] = None,
-    priority_level: int = 1,
-    debug_name: Optional[str] = None,
-) -> Callable[[Callable[..., T]], ReadonlyRef[T]]:
-    ...
-
-
-def ref_computed(
-    fn: Optional[Union[Callable[[], T], TInstanceCall[T]]] = None,
-    *,
-    desc="",
-    debug_trigger: Optional[Callable[..., None]] = None,
-    priority_level: int = 1,
-    debug_name: Optional[str] = None,
-) -> Union[ReadonlyRef[T], Callable[[Callable[..., T]], ReadonlyRef[T]]]:
-    kws = {
-        "debug_trigger": debug_trigger,
-        "priority_level": priority_level,
-        "debug_name": debug_name,
-    }
-
-    if fn:
-        if _is_class_define_method(fn):
-            return cast(
-                ref_computed_method[T],
-                ref_computed_method(fn, computed_args=kws),  # type: ignore
-            )  # type: ignore
-
-        getter = signe.Computed(
-            cast(Callable[[], T], fn),
-            **kws,
-            scope=_CLIENT_SCOPE_MANAGER.get_current_scope(),
-            scheduler=get_uiScheduler(),
-        )
-        return cast(DescReadonlyRef[T], getter)
-
-    else:
-
-        def wrap(fn: Callable[[], T]):
-            return ref_computed(fn, **kws)
-
-        return wrap
-
-
-def _is_class_define_method(fn: Callable):
-    has_name = hasattr(fn, "__name__")
-    qualname_prefix = f".<locals>.{fn.__name__}" if has_name else ""
-
-    return (
-        hasattr(fn, "__qualname__")
-        and has_name
-        and "." in fn.__qualname__
-        and qualname_prefix != fn.__qualname__[-len(qualname_prefix) :]
-        and (isinstance(fn, types.FunctionType))
-    )
-
-
-class ref_computed_method(Generic[T]):
-    __isabstractmethod__: bool
-
-    def __init__(self, fget: Callable[[Any], T], computed_args: Dict) -> None:
-        self._fget = fget
-        self._computed_args = computed_args
-        self._instance_map: WeakValueDictionary[
-            int, TReadonlyRef[T]
-        ] = WeakValueDictionary()
-
-    def __get_computed(self, instance):
-        ins_id = id(instance)
-        if ins_id not in self._instance_map:
-            cp = signe.Computed(
-                partial(self._fget, instance),
-                **self._computed_args,
-                scope=_CLIENT_SCOPE_MANAGER.get_current_scope(),
-                scheduler=get_uiScheduler(),
-                capture_parent_effect=False,
-            )
-            self._instance_map[ins_id] = cp  # type: ignore
-
-        return self._instance_map[ins_id]
-
-    def __get__(self, __instance: Any, __owner: Optional[type] = None):
-        return cast(TRef[T], self.__get_computed(__instance))
+_T_effect_refreshable_refs = Union[
+    TGetterOrReadonlyRef,
+    RefWrapper,
+    Sequence[TGetterOrReadonlyRef],
+    _TMaybeRef,
+    Sequence[_TMaybeRef],
+]
 
 
 class effect_refreshable:
-    def __init__(self, fn: Callable, refs: Union[TRef, Sequence[TRef]] = []) -> None:
+    def __init__(self, fn: Callable, refs: _T_effect_refreshable_refs = []) -> None:
         self._fn = fn
-        self._refs = refs if isinstance(refs, Sequence) else [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: Union[TRef, Sequence[TRef]]):
+    def on(refs: _T_effect_refreshable_refs):
         def warp(
             fn: Callable,
         ):
@@ -323,7 +181,7 @@ class effect_refreshable:
         if len(self._refs) == 0:
             runner = effect(runner)
         else:
-            runner = on(self._refs)(runner)
+            runner = on(self._refs)(runner)  # type: ignore
 
         return runner
 
@@ -334,6 +192,7 @@ def on(
     priority_level=1,
     effect_kws: Optional[Dict[str, Any]] = None,
     deep: bool = True,
+    scope: Optional[Scope] = None,
 ):
     """Watches one or more reactive data sources and invokes a callback function when the sources change.
 
@@ -362,7 +221,7 @@ def on(
             fn,
             onchanges=onchanges,
             effect_kws=effect_kws,
-            scope=_CLIENT_SCOPE_MANAGER.get_current_scope(),
+            scope=scope or _CLIENT_SCOPE_MANAGER.get_current_scope(),
             deep=deep,
             scheduler=get_uiScheduler(),
         )

ex4nicegui/utils/types.py

@@ -0,0 +1,16 @@
+import signe
+from signe.core.protocols import ComputedResultProtocol
+from typing import (
+    TypeVar,
+)
+
+T = TypeVar("T")
+
+
+TReadonlyRef = ComputedResultProtocol[T]
+ReadonlyRef = TReadonlyRef[T]
+DescReadonlyRef = TReadonlyRef[T]
+TGetterOrReadonlyRef = signe.TGetter[T]
+_TMaybeRef = signe.TMaybeSignal[T]
+TRef = signe.TSignal[T]
+Ref = TRef[T]

ex4nicegui/version.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__: str = importlib.metadata.version("ex4nicegui")

{ex4nicegui-0.6.7.dist-info → ex4nicegui-0.6.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.6.7
+Version: 0.6.9
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules
 Home-page: https://github.com/CrystalWindSnake/ex4nicegui
 License: MIT
@@ -604,7 +604,7 @@ rxui.label("bind to ref_computed").bind_classes(
 
 ---
 
-绑定为列表
+绑定为列表或单个字符串的响应式变量
 
 ```python
 bg_color = to_ref("red")
@@ -617,10 +617,11 @@ rxui.select(["red", "green", "yellow"], label="bg color", value=bg_color)
 rxui.select(["red", "green", "yellow"], label="text color", value=text_color)
 
 rxui.label("binding to arrays").bind_classes([bg_color_class, text_color_class])
-
+rxui.label("binding to single string").bind_classes(bg_color_class)
 ```
 
-列表中每个元素为返回类名的响应式变量
+- 列表中每个元素为返回类名的响应式变量
+
 
 ---
 
@@ -887,6 +888,62 @@ rxui.radio(names, value=current_tab).props("inline")
 
 rxui.label(lambda: f"当前 tab 为:{current_tab.value}")
 ```
+---
+
+### lazy_tab_panels
+
+懒加载模式下，只有当前激活的 tab 才会渲染。
+```python
+from ex4nicegui import to_ref, rxui, on, deep_ref
+
+current_tab = to_ref("t1")
+
+with rxui.tabs(current_tab):
+    ui.tab("t1")
+    ui.tab("t2")
+
+with rxui.lazy_tab_panels(current_tab) as panels:
+
+    @panels.add_tab_panel("t1")
+    def _():
+        ui.notify("Hello from t1")
+
+    @panels.add_tab_panel("t2")
+    def _():
+        ui.notify("Hello from t2")
+
+```
+
+页面加载后，立刻显示 "Hello from t1"。当切换到 "t2" 页签，才会显示 "Hello from t2"。
+
+---
+
+### scoped_style
+
+`scoped_style` 方法允许你创建限定在组件内部的样式。
+
+```python
+# 所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style("*", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+
+# 所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style(":hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+```
 
 
 ---