ex4nicegui 0.2.18__tar.gz → 0.3.1__tar.gz

{ex4nicegui-0.2.18 → ex4nicegui-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.2.18
+Version: 0.3.1
 Summary: ...
 Home-page: 
 Author: carson_jia

ex4nicegui-0.3.1/README.md

@@ -0,0 +1,209 @@
+# ex4nicegui
+[ENGLISH README](./README.en.md)
+
+- [教程](#教程)
+- [安装](#-安装)
+- [使用](#-使用)
+- [功能](#-功能)
+- [BI 模块](#bi-模块)
+
+对 [nicegui](https://github.com/zauberzeug/nicegui) 做的扩展库。内置响应式组件，完全实现数据响应式界面编程。
+
+
+## 教程
+[头条文章-秒杀官方实现，python界面库，去掉90%事件代码的nicegui](https://www.toutiao.com/item/7253786340574265860/)
+
+[微信公众号-秒杀官方实现，python界面库，去掉90%事件代码的nicegui](https://mp.weixin.qq.com/s?__biz=MzUzNDk1MTc5Mw==&mid=2247486796&idx=1&sn=457ed6fb9d6a25145f7704d5197d670d&chksm=fa8daf52cdfa2644bede50ae7f2551162ecaedecafec231ee4ce8f28775a599f8669ecf06af1#rd)
+
+
+## 📦 安装
+
+```
+pip install ex4nicegui -U
+```
+
+## 🦄 使用
+
+```python
+from nicegui import ui
+from ex4nicegui import ref_computed, effect, to_ref
+from ex4nicegui.reactive import rxui
+
+# 定义响应式数据
+r_input = to_ref("")
+
+# 按照 nicegui 使用方式传入响应式数据即可
+rxui.input(value=r_input)
+rxui.label(r_input)
+
+ui.run()
+```
+![](./asset/sync_input.gif)
+
+
+### 提供 echarts 图表组件
+
+```python
+from nicegui import ui
+from ex4nicegui import ref_computed, effect, to_ref
+from ex4nicegui.reactive import rxui
+
+r_input = to_ref("")
+
+# ref_computed 创建只读响应式变量
+# 函数中使用任意其他响应式变量，会自动关联
+@ref_computed
+def cp_echarts_opts():
+    return {
+        "title": {"text": r_input.value}, #字典中使用任意响应式变量，通过 .value 获取值
+        "xAxis": {
+            "type": "category",
+            "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
+        },
+        "yAxis": {"type": "value"},
+        "series": [
+            {
+                "data": [120, 200, 150, 80, 70, 110, 130],
+                "type": "bar",
+                "showBackground": True,
+                "backgroundStyle": {"color": "rgba(180, 180, 180, 0.2)"},
+            }
+        ],
+    }
+
+input = rxui.input("输入内容，图表标题会同步", value=r_input)
+# 通过响应式组件对象的 element 属性，获取原生 nicegui 组件对象
+input.element.classes("w-full")
+
+rxui.echarts(cp_echarts_opts)
+
+ui.run()
+```
+![](./asset/asyc_echarts_title.gif)
+
+
+
+## BI 模块
+
+以最精简的 apis 创建可交互的数据可视化报表
+
+![](./asset/bi_examples1.gif)
+
+```python
+from nicegui import ui
+import pandas as pd
+import numpy as np
+from ex4nicegui import bi
+from ex4nicegui import effect, effect_refreshable
+from pyecharts.charts import Bar
+
+
+# data ready
+def gen_data():
+    np.random.seed(265)
+    field1 = ["a1", "a2", "a3", "a4"]
+    field2 = [f"name{i}" for i in range(1, 11)]
+    df = (
+        pd.MultiIndex.from_product([field1, field2], names=["cat", "name"])
+        .to_frame()
+        .reset_index(drop=True)
+    )
+    df[["idc1", "idc2"]] = np.random.randint(50, 1000, size=(len(df), 2))
+    return df
+
+
+df = gen_data()
+
+# 创建数据源
+ds = bi.data_source(df)
+
+# ui
+ui.query(".nicegui-content").classes("items-stretch no-wrap")
+
+with ui.row().classes("justify-evenly"):
+    # 基于数据源 `ds` 创建界面组件
+    ds.ui_select("cat").classes("min-w-[10rem]")
+    ds.ui_select("name").classes("min-w-[10rem]")
+
+
+with ui.grid(columns=2):
+    # 使用字典配置图表
+    @ds.ui_echarts
+    def bar1(data: pd.DataFrame):
+        data = data.groupby("name").agg({"idc1": "sum", "idc2": "sum"}).reset_index()
+
+        return {
+            "xAxis": {"type": "value"},
+            "yAxis": {
+                "type": "category",
+                "data": data["name"].tolist(),
+                "inverse": True,
+            },
+            "legend": {"textStyle": {"color": "gray"}},
+            "series": [
+                {"type": "bar", "name": "idc1", "data": data["idc1"].tolist()},
+                {"type": "bar", "name": "idc2", "data": data["idc2"].tolist()},
+            ],
+        }
+
+    bar1.classes("h-[20rem]")
+
+    # 使用pyecharts配置图表
+    @ds.ui_echarts
+    def bar2(data: pd.DataFrame):
+        data = data.groupby("name").agg({"idc1": "sum", "idc2": "sum"}).reset_index()
+
+        return (
+            Bar()
+            .add_xaxis(data["name"].tolist())
+            .add_yaxis("idc1", data["idc1"].tolist())
+            .add_yaxis("idc2", data["idc2"].tolist())
+        )
+
+    bar2.classes("h-[20rem]")
+
+    # 绑定点击事件，即可实现跳转
+    @bar2.on_chart_click
+    def _(e):
+        ui.open(f"/details/{e.name}", new_tab=True)
+
+
+# 利用响应式机制，你可以随意组合原生 nicegui 组件
+label_a1_total = ui.label("")
+
+
+# 当 ds 有变化，都会触发此函数
+@effect
+def _():
+    # filtered_data 为过滤后的 DataFrame
+    df = ds.filtered_data
+    total = df[df["cat"] == "a1"]["idc1"].sum()
+    label_a1_total.text = f"idc1 total(cat==a1):{total}"
+
+
+# 你也可以使用 `effect_refreshable`,但需要注意函数中的组件每次都被重建
+@effect_refreshable
+def _():
+    df = ds.filtered_data
+    total = df[df["cat"] == "a2"]["idc1"].sum()
+    ui.label(f"idc1 total(cat==a2):{total}")
+
+
+# 当点击图表系列时，跳转的页面
+@ui.page("/details/{name}")
+def details_page(name: str):
+    ui.label("This table data will not change")
+    ui.aggrid.from_pandas(ds.data.query(f'name=="{name}"'))
+
+    ui.label("This table will change when the homepage data changes. ")
+
+    @bi.data_source
+    def new_ds():
+        return ds.filtered_data[["name", "idc1", "idc2"]]
+
+    new_ds.ui_aggrid()
+
+
+ui.run()
+```
+

{ex4nicegui-0.2.18 → ex4nicegui-0.3.1}/ex4nicegui/__init__.py

@@ -16,4 +16,4 @@ from signe import batch
 from ex4nicegui.experimental_ import gridLayout as exp_ui
 
 
-__version__ = "0.2.18"
+__version__ = "0.3.1"

ex4nicegui-0.3.1/ex4nicegui/bi/__init__.py

@@ -0,0 +1,13 @@
+from .index import data_source
+from .elements.text import ui_title, ui_header, ui_subheader
+from .elements.containers import ui_cols
+from .elements.layouts import ui_left_drawer
+
+__all__ = [
+    "data_source",
+    "ui_left_drawer",
+    "ui_title",
+    "ui_header",
+    "ui_subheader",
+    "ui_cols",
+]

ex4nicegui-0.3.1/ex4nicegui/bi/dataSource.py

@@ -0,0 +1,203 @@
+from typing import Callable, Dict, List, Optional, Set, cast
+from ex4nicegui import to_ref, ref_computed, on
+from nicegui import globals as ng_globals, Client, ui
+
+from dataclasses import dataclass, field
+from . import types
+from .protocols import IDataSourceAble
+
+_TComponentUpdateCallback = Callable[[], None]
+
+
+@dataclass
+class Filter:
+    callback: types._TFilterCallback
+
+
+@dataclass(frozen=True)
+class ComponentInfoKey:
+    client_id: types._TNgClientID
+    element_id: types._TElementID
+
+
+@dataclass
+class ComponentInfo:
+    key: ComponentInfoKey
+    update_callback: Optional[_TComponentUpdateCallback] = None
+    filter: Optional[Filter] = None
+    exclude_keys: Set[ComponentInfoKey] = field(default_factory=set)
+
+    def __eq__(self, other):
+        return isinstance(other, ComponentInfo) and self.key == other.key
+
+
+class ComponentMap:
+    def __init__(self) -> None:
+        self._client_map: Dict[
+            types._TNgClientID, Dict[types._TElementID, ComponentInfo]
+        ] = {}
+
+    def has_client_record(self, client_id: types._TNgClientID):
+        return client_id in self._client_map
+
+    def add_info(self, info: ComponentInfo):
+        client_id = info.key.client_id
+        element_id = info.key.element_id
+
+        if client_id not in self._client_map:
+            self._client_map[client_id] = {element_id: info}
+
+        element_map = self._client_map[client_id]
+
+        if element_id not in element_map:
+            element_map[element_id] = info
+
+    def remove_client(self, client_id: types._TNgClientID):
+        if client_id in self._client_map:
+            del self._client_map[client_id]
+
+    def has_record(self, key: ComponentInfoKey):
+        return (
+            key.client_id in self._client_map
+            and key.element_id in self._client_map[key.client_id]
+        )
+
+    def set_filter(
+        self,
+        client_id: types._TNgClientID,
+        element_id: types._TElementID,
+        filter: Filter,
+    ):
+        self._client_map[client_id][element_id].filter = filter
+
+    def get_all_info(self):
+        return (
+            info for ele_map in self._client_map.values() for info in ele_map.values()
+        )
+
+    def get_info(self, key: ComponentInfoKey) -> ComponentInfo:
+        return self._client_map[key.client_id][key.element_id]
+
+
+class DataSource:
+    _global_id_count: types._TDataSourceId = 0
+
+    def __init__(self, data: IDataSourceAble) -> None:
+        DataSource._global_id_count += 1
+        self.__id = DataSource._global_id_count
+
+        self._idataSource = data
+
+        data_fn = lambda: data.get_data()
+        data_fn = ref_computed(data_fn)
+
+        self.__filters = to_ref(cast(List[Filter], []))
+
+        @ref_computed
+        def apply_filters():
+            df = data_fn.value
+            for f in self.__filters.value:
+                df = f.callback(df)
+
+            return df
+
+        self.__filtered_data = apply_filters
+
+        self.__data = data_fn
+        self._component_map = ComponentMap()
+
+        @on(data_fn)
+        def _():
+            self.__notify_update()
+
+    @property
+    def data(self):
+        return self.__data.value
+
+    @property
+    def filtered_data(self):
+        return self.__filtered_data.value
+
+    @property
+    def id(self):
+        return self.__id
+
+    def get_component_info_key(self, element_id: types._TElementID):
+        client_id = ng_globals.get_client().id
+        return ComponentInfoKey(client_id, element_id)
+
+    def get_filtered_data(self, element: ui.element):
+        data = self._idataSource.get_data()
+
+        # note:must be use client id of the element
+        key = ComponentInfoKey(element.client.id, element.id)
+        current_info = self._component_map.get_info(key)
+
+        filters = [
+            info.filter.callback
+            for info in self._component_map.get_all_info()
+            if current_info.key != info.key
+            and (info.key not in current_info.exclude_keys)
+            and info.filter
+        ]
+
+        return self._idataSource.apply_filters(data, filters)
+
+    def _register_component(
+        self,
+        element_id: types._TElementID,
+        update_callback: Optional[_TComponentUpdateCallback] = None,
+    ):
+        ng_client = ng_globals.get_client()
+        client_id = ng_client.id
+
+        if not self._component_map.has_client_record(client_id):
+
+            @ng_client.on_disconnect
+            def _(e: Client):
+                if not e.shared:
+                    self._component_map.remove_client(e.id)
+
+        info = ComponentInfo(ComponentInfoKey(client_id, element_id), update_callback)
+        self._component_map.add_info(info)
+
+        return info
+
+    def send_filter(self, element_id: types._TElementID, filter: Filter):
+        client_id = ng_globals.get_client().id
+        key = ComponentInfoKey(client_id, element_id)
+
+        if not self._component_map.has_record(key):
+            raise ValueError("element not register")
+
+        self._component_map.set_filter(client_id, element_id, filter)
+
+        trigger_info = self._component_map.get_info(
+            ComponentInfoKey(client_id, element_id)
+        )
+
+        self.__notify_update(trigger_info)
+        self.__filters.value = [
+            info.filter for info in self._component_map.get_all_info() if info.filter
+        ]
+
+        return self
+
+    def __notify_update(self, trigger_info: Optional[ComponentInfo] = None):
+        # nodify every component
+        for current_info in self._component_map.get_all_info():
+            # not nodify the self triggering
+            if trigger_info and current_info.key == trigger_info.key:
+                continue
+
+            update_callback = current_info.update_callback
+            if update_callback:
+                update_callback()
+
+    def on_source_update(
+        self,
+        element_id: types._TElementID,
+        callback: _TComponentUpdateCallback,
+    ):
+        key = self.get_component_info_key(element_id)
+        self._component_map.get_info(key).update_callback = callback

ex4nicegui-0.3.1/ex4nicegui/bi/dataSourceFacade.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, TypeVar, Generic, Union, cast
+from nicegui import ui
+from .dataSource import DataSource, Filter
+from . import types as bi_types
+from .elements.ui_select import ui_select
+from .elements.ui_radio import ui_radio
+from .elements.ui_slider import ui_slider
+from .elements.ui_range import ui_range
+from .elements.ui_echarts import ui_echarts
+from .elements.ui_aggrid import ui_aggrid
+
+
+_TData = TypeVar("_TData")
+
+
+class DataSourceFacade(Generic[_TData]):
+    def __init__(self, ds: DataSource) -> None:
+        self._dataSource = ds
+
+    @property
+    def data(self) -> _TData:
+        """Data without any filtering"""
+        return cast(_TData, self._dataSource.data)
+
+    @property
+    def filtered_data(self) -> _TData:
+        """Data after filtering"""
+        return cast(_TData, self._dataSource.filtered_data)
+
+    def ui_select(self, column: str, *, clearable=True, multiple=True, **kwargs):
+        """
+        Creates a user interface select box.
+
+        Parameters:
+            column (str): The column name of the data source.
+            clearable (bool, optional): Whether to allow clearing the content of the select box. Default is True.
+            multiple (bool, optional): Whether to allow multiple selections.
+            **kwargs: Additional optional parameters that will be passed to the ui.select constructor.
+
+        Returns:
+            SelectResult: An instance of a user interface select box.
+        """
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
+        kws.update(kwargs)
+        return ui_select(**kws)
+
+    def ui_aggrid(self, **kwargs):
+        """
+        Creates aggrid table.
+
+        Parameters:
+            **kwargs: Additional optional parameters that will be passed to the ui.aggrid constructor.
+
+        Returns:
+            ui.aggrid: aggrid table.
+        """
+        return ui_aggrid(self, **kwargs)
+
+    def ui_radio(self, column: str, **kwargs):
+        """
+        Creates radio Selection.
+
+        Parameters:
+            column (str): The column name of the data source.
+            **kwargs: Additional optional parameters that will be passed to the ui.radio constructor.
+
+        Returns:
+            RadioResult: An radio Selection.
+        """
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
+        kws.update(kwargs)
+        return ui_radio(**kws)
+
+    def ui_slider(self, column: str, **kwargs):
+        """
+        Creates Slider.
+
+        Parameters:
+            column (str): The column name of the data source.
+            **kwargs: Additional optional parameters that will be passed to the ui.slider constructor.
+
+        Returns:
+            ui.radio: An Slider.
+        """
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
+        kws.update(kwargs)
+        return ui_slider(**kws)
+
+    def ui_range(self, column: str, **kwargs):
+        """
+        Creates Range.
+
+        Parameters:
+            column (str): The column name of the data source.
+            **kwargs: Additional optional parameters that will be passed to the ui.slider constructor.
+
+        Returns:
+            QRange: An Range.
+        """
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
+        kws.update(kwargs)
+        return ui_range(**kws)
+
+    def ui_echarts(
+        self, fn: Callable[[Any], Union[Dict, "pyecharts.Base"]]  # pyright: ignore
+    ):
+        """Create charts
+
+        Args:
+            fn (Callable[[Any], Union[Dict, "pyecharts.Base"]]): builder function.
+
+        ## Examples
+
+        Support pyecharts
+
+        ```py
+        import pandas as pd
+        from ex4nicegui import bi
+        from pyecharts.charts import Bar
+
+        df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
+        ds = bi.data_source(df)
+
+        @ds.ui_echarts
+        def bar(data: pd.DataFrame):
+            c = (
+                Bar()
+                .add_xaxis(data["name"].tolist())
+                .add_yaxis("value", data["value"].tolist())
+            )
+
+            return c
+
+        bar.classes("h-[20rem]")
+        ```
+
+        """
+        return ui_echarts(self, fn)
+
+    def send_filter(
+        self, element: ui.element, filter: bi_types._TFilterCallback[_TData]
+    ):
+        ele_id = element.id
+        key = self._dataSource.get_component_info_key(ele_id)
+        if not self._dataSource._component_map.has_record(key):
+            self._dataSource._register_component(ele_id)
+        self._dataSource.send_filter(ele_id, Filter(filter))

ex4nicegui-0.3.1/ex4nicegui/bi/elements/containers.py

@@ -0,0 +1,13 @@
+from nicegui import ui
+from ex4nicegui.layout import grid_box
+
+
+def ui_cols(num: int, min_width="0"):
+    with grid_box(template_columns=f"repeat({num},1fr)").classes(
+        "justify-between"
+    ) as gb:
+        divs = [ui.column() for _ in range(num)]
+
+    gb.grid_box(template_columns="1fr", break_point="<sm[0-599.99px]")
+
+    return divs

ex4nicegui-0.3.1/ex4nicegui/bi/elements/layouts.py

@@ -0,0 +1,28 @@
+from nicegui import ui
+from ex4nicegui.reactive import rxui
+from ex4nicegui import to_ref
+
+
+def ui_left_drawer():
+    drawer_show = to_ref(True)
+
+    with rxui.drawer("left", value=drawer_show) as drawer:
+        with ui.page_sticky("top-right", x_offset=10, y_offset=10):
+            icon_close = (
+                rxui.icon(name="close")
+                .classes("cursor-pointer")
+                .props("round ")
+                .bind_visible(drawer_show)
+            )
+            icon_close.on("click", drawer.toggle)
+
+    with ui.page_sticky("top-left", x_offset=10, y_offset=10):
+        icon_close = (
+            rxui.icon(name="keyboard_arrow_right", size="1.2rem")
+            .classes("cursor-pointer")
+            .props("round ")
+            .bind_not_visible(drawer_show)
+        )
+        icon_close.on("click", drawer.toggle)
+
+    return drawer.element

ex4nicegui-0.3.1/ex4nicegui/bi/elements/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+from typing import Optional, TypeVar, Generic, TYPE_CHECKING, Union
+from nicegui import ui
+
+if TYPE_CHECKING:
+    from ex4nicegui.bi.dataSource import DataSource
+
+
+_T_ELEMENT = TypeVar("_T_ELEMENT", bound=ui.element)
+
+
+class UiResult(Generic[_T_ELEMENT]):
+    def __init__(self, element: _T_ELEMENT, dataSource: "DataSource") -> None:
+        self.__element = element
+        self._dataSource = dataSource
+
+    @property
+    def element(self):
+        return self.__element
+
+    @property
+    def id(self):
+        return self.element.id
+
+    def classes(
+        self,
+        add: Optional[str] = None,
+        *,
+        remove: Optional[str] = None,
+        replace: Optional[str] = None,
+    ):
+        self.element.classes(add, remove=remove, replace=replace)
+        return self
+
+    def props(
+        self,
+        add: Optional[str] = None,
+        *,
+        remove: Optional[str] = None,
+    ):
+        self.element.props(add, remove=remove)
+        return self
+
+    def cancel_linkage(self, *source: Union[ui.element, "UiResult"]):
+        get_info_key = self._dataSource.get_component_info_key
+
+        key = get_info_key(self.element.id)
+
+        info = self._dataSource._component_map.get_info(key)
+
+        for s in source:
+            res_key = get_info_key(s.id)
+            info.exclude_keys.add(res_key)
+
+        return self