ex4nicegui 0.2.17__tar.gz → 0.3.0__tar.gz

{ex4nicegui-0.2.17 → ex4nicegui-0.3.0}/PKG-INFO

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

ex4nicegui-0.3.0/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.17 → ex4nicegui-0.3.0}/ex4nicegui/__init__.py

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

ex4nicegui-0.3.0/ex4nicegui/bi/__init__.py

@@ -0,0 +1,3 @@
+from .index import data_source
+
+__all__ = ["data_source"]

ex4nicegui-0.3.0/ex4nicegui/bi/dataSource.py

@@ -0,0 +1,174 @@
+from typing import Dict, List, Optional, cast
+from ex4nicegui import to_ref, ref_computed, on
+from nicegui import globals, Client
+
+from dataclasses import dataclass
+from . import types
+from .protocols import IDataSourceAble
+
+
+@dataclass
+class DataSourceInfo:
+    source: "DataSource"
+    update_callback: types._TSourceBuildFn
+
+
+@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: types._TComponentUpdateCallback
+    filter: Optional[Filter] = None
+
+
+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, client_id: types._TNgClientID, element_id: types._TElementID):
+        return (
+            client_id in self._client_map and element_id in self._client_map[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()
+        )
+
+
+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 _register_component(
+        self,
+        element_id: types._TElementID,
+        update_callback: types._TComponentUpdateCallback,
+    ):
+        ng_client = 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)
+
+        self._component_map.add_info(
+            ComponentInfo(ComponentInfoKey(client_id, element_id), update_callback)
+        )
+
+        return self
+
+    def send_filter(self, element_id: types._TElementID, filter: Filter):
+        client_id = globals.get_client().id
+
+        if not self._component_map.has_record(client_id, element_id):
+            raise ValueError("element not register")
+
+        self._component_map.set_filter(client_id, element_id, filter)
+
+        self.__notify_update([ComponentInfoKey(client_id, element_id)])
+        return self
+
+    def __notify_update(self, ignore_keys: Optional[List[ComponentInfoKey]] = None):
+        ignore_keys = ignore_keys or []
+        ignore_ids_set = set(ignore_keys)
+
+        # nodify every component
+        for current_info in self._component_map.get_all_info():
+            if current_info.key in ignore_ids_set:
+                continue
+
+            # apply filters ,except current target
+            filters = [
+                info.filter.callback
+                for info in self._component_map.get_all_info()
+                if (info.key != current_info.key) and info.filter
+            ]
+
+            new_data = self._idataSource.apply_filters(self.__data.value, filters)
+            current_info.update_callback(new_data)
+
+        self.__filters.value = [
+            info.filter for info in self._component_map.get_all_info() if info.filter
+        ]

ex4nicegui-0.3.0/ex4nicegui/bi/dataSourceFacade.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, TypeVar, Generic, Union, cast
+from nicegui import ui
+from ex4nicegui import ref_computed
+from ex4nicegui.reactive import rxui
+from .dataSource import DataSource, Filter
+from ex4nicegui.reactive.EChartsComponent.ECharts import echarts
+
+
+_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
+    ) -> ui.select:
+        """
+        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:
+            ui.select: An instance of a user interface select box.
+        """
+        options = self._dataSource._idataSource.duplicates_column_values(
+            self.data, column
+        )
+        kwargs.update(
+            {
+                "options": options,
+                "multiple": multiple,
+                "clearable": clearable,
+                "label": column,
+            }
+        )
+
+        cp = ui.select(**kwargs).props("use-chips outlined")
+
+        def onchange(e):
+            value = None
+            if e.args:
+                if isinstance(e.args, list):
+                    value = [arg["label"] for arg in e.args]
+                else:
+                    value = e.args["label"]
+
+            cp.value = value
+
+            def data_filter(data):
+                if cp.value is None or not cp.value:
+                    return data
+
+                cond = None
+                if isinstance(cp.value, list):
+                    cond = data[column].isin(cp.value)
+                else:
+                    cond = data[column] == cp.value
+                return data[cond]
+
+            self._dataSource.send_filter(cp.id, Filter(data_filter))
+
+        cp.on("update:modelValue", onchange)
+
+        def on_source_update(data):
+            options = self._dataSource._idataSource.duplicates_column_values(
+                data, column
+            )
+            value = cp.value
+
+            # Make the value within the options
+            if isinstance(value, list):
+                value = list(set(value) & set(options))
+            else:
+                if value not in options:
+                    value = ""
+
+            cp.set_options(options, value=value)
+
+        self._dataSource._register_component(cp.id, on_source_update)
+
+        return cp
+
+    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.
+        """
+        kwargs.update(
+            {"options": self._dataSource._idataSource.get_aggrid_options(self.data)}
+        )
+
+        cp = ui.aggrid(**kwargs)
+
+        def on_source_update(data):
+            cp._props["options"] = self._dataSource._idataSource.get_aggrid_options(
+                data
+            )
+            cp.update()
+
+        on_source_update(self.filtered_data)
+
+        self._dataSource._register_component(cp.id, on_source_update)
+
+        return cp
+
+    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:
+            ui.radio: An radio Selection.
+        """
+        options = self._dataSource._idataSource.duplicates_column_values(
+            self.data, column
+        )
+        kwargs.update({"options": options})
+
+        cp = ui.radio(**kwargs)
+
+        def onchange(e):
+            cp.value = cp.options[e.args]
+
+            def data_filter(data):
+                if cp.value not in cp.options:
+                    return data
+                cond = data[column] == cp.value
+                return data[cond]
+
+            self._dataSource.send_filter(cp.id, Filter(data_filter))
+
+        cp.on("update:modelValue", onchange)
+
+        def on_source_update(data):
+            options = self._dataSource._idataSource.duplicates_column_values(
+                data, column
+            )
+            value = cp.value
+            if value not in options:
+                value = ""
+
+            cp.set_options(options, value=value)
+
+        self._dataSource._register_component(cp.id, on_source_update)
+
+        return cp
+
+    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.
+        """
+        self._dataSource._idataSource.slider_check(self.data, column)
+
+        min, max = self._dataSource._idataSource.slider_min_max(self.data, column)
+        kwargs.update({"min": min, "max": max})
+
+        cp = ui.slider(**kwargs).props("label label-always switch-label-side")
+
+        def onchange():
+            def data_filter(data):
+                if cp.value is None or cp.value < min:
+                    return data
+                cond = data[column] == cp.value
+                return data[cond]
+
+            self._dataSource.send_filter(cp.id, Filter(data_filter))
+
+        cp.on("change", onchange)
+
+        def on_source_update(data):
+            min, max = self._dataSource._idataSource.slider_min_max(data, column)
+            if min is None or max is None:
+                cp.value = None
+            else:
+                cp._props["min"] = min
+                cp._props["max"] = max
+
+        self._dataSource._register_component(cp.id, on_source_update)
+
+        return cp
+
+    def ui_echarts(
+        self, fn: Callable[[Any], Union[Dict, "pyecharts.Base"]]  # pyright: ignore
+    ) -> echarts:
+        """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]")
+        ```
+
+        """
+
+        @ref_computed
+        def chart_options():
+            options = fn(self.filtered_data)
+            if isinstance(options, Dict):
+                return options
+
+            import simplejson as json
+            from pyecharts.charts.chart import Base
+
+            if isinstance(options, Base):
+                return cast(Dict, json.loads(options.dump_options()))
+
+        cp = rxui.echarts(chart_options)  # type: ignore
+
+        return cp.element  # type: ignore