nicegui 3.4.0__tar.gz → 3.5.0__tar.gz

{nicegui-3.4.0 → nicegui-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nicegui
-Version: 3.4.0
+Version: 3.5.0
 Summary: Create web-based user interfaces with Python. The nice way.
 License-Expression: MIT
 License-File: LICENSE
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: altair
+Provides-Extra: anywidget
 Provides-Extra: highcharts
 Provides-Extra: matplotlib
 Provides-Extra: native
@@ -23,6 +25,8 @@ Provides-Extra: redis
 Requires-Dist: Pygments (>=2.15.1,<3.0.0)
 Requires-Dist: aiofiles (>=23.1.0)
 Requires-Dist: aiohttp (>=3.10.2)
+Requires-Dist: altair (>=6.0.0) ; extra == "altair"
+Requires-Dist: anywidget (>=0.9.21) ; extra == "anywidget"
 Requires-Dist: certifi (>=2024.07.04)
 Requires-Dist: docutils (>=0.19.0)
 Requires-Dist: fastapi (>=0.109.1,!=0.123.5)

{nicegui-3.4.0 → nicegui-3.5.0}/nicegui/client.py

@@ -304,6 +304,7 @@ class Client:
         document_id = self._socket_to_document_id.pop(socket_id)
         self._cancel_delete_task(document_id)
         self._num_connections[document_id] -= 1
+        tab_id_to_close = self.tab_id
         self.tab_id = None
 
         for t in self.disconnect_handlers:
@@ -316,6 +317,7 @@ class Client:
             if self._num_connections[document_id] == 0:
                 self._num_connections.pop(document_id)
                 self._delete_tasks.pop(document_id)
+                await core.app.storage.close_tab(tab_id_to_close)
                 self.delete()
         self._delete_tasks[document_id] = \
             background_tasks.create(delete_content(), name=f'delete content {document_id}')
@@ -388,6 +390,8 @@ class Client:
         self.outbox.stop()
         del Client.instances[self.id]
         self._deleted = True
+        self._connected.set()  # for terminating connected() waits
+        self._connected.clear()
 
     def check_existence(self) -> None:
         """Check if the client still exists and print a warning if it doesn't."""

nicegui-3.5.0/nicegui/defaults.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from typing_extensions import ParamSpec
+
+from .dataclasses import KWONLY_SLOTS
+from .element import Element
+
+T = TypeVar('T')
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+@dataclass(**KWONLY_SLOTS)
+class Sentinel:
+    key: str | None
+
+    def __or__(self, other: T) -> T:
+        return SentinelValue(key=self.key, default=other)  # type: ignore[return-value]
+
+
+@dataclass(**KWONLY_SLOTS)
+class SentinelValue:
+    key: str | None
+    default: Any
+
+
+class SentinelFactory:
+
+    def __getitem__(self, prop_key: str) -> Sentinel:
+        return Sentinel(key=prop_key)
+
+
+DEFAULT_PROPS = SentinelFactory()
+DEFAULT_PROP = Sentinel(key=None)
+
+
+def resolve_defaults(original_func: Callable[P, R]) -> Callable[P, R]:
+    """This decorator makes the function resolve default properties set via ``default_props``.
+
+    If a parameter has a default value which looks like ``DEFAULT_PROPS['prop-key'] | default_value``,
+    the actual value will be taken from the element's ``_default_props`` dictionary with key "prop-key" if present,
+    otherwise the specified ``default_value`` is used.
+
+    If a parameter has a default value which looks like ``DEFAULT_PROP | default_value``,
+    the dictionary key will be inferred from the parameter name (converting snake_case to kebab-case).
+    """
+    signature = inspect.signature(original_func)
+
+    @functools.wraps(original_func)
+    def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
+        bound = signature.bind(*args, **kwargs)
+        bound.apply_defaults()
+
+        el: Element = bound.arguments['self']
+
+        for param_name, value in bound.arguments.items():
+            if isinstance(value, SentinelValue):
+                key = value.key or param_name.replace('_', '-')
+                kwargs[param_name] = el._default_props.get(key, value.default)  # pylint: disable=protected-access
+        return original_func(*args, **kwargs)
+
+    return decorated

{nicegui-3.4.0 → nicegui-3.5.0}/nicegui/dependencies.py

@@ -4,7 +4,7 @@ import functools
 from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING, Callable, ClassVar
 
 from . import core
 from .dataclasses import KWONLY_SLOTS
@@ -21,6 +21,14 @@ class Component:
     key: str
     name: str
     path: Path
+    _keys: ClassVar[set[str]] = set()
+    _names: ClassVar[set[str]] = set()
+
+    def __post_init__(self) -> None:
+        assert self.key not in self._keys, f'Duplicate key "{self.key}" for {self.__class__.__name__} {self.path}'
+        assert self.name not in self._names, f'Duplicate name "{self.name}" for {self.__class__.__name__} {self.path}'
+        self._keys.add(self.key)
+        self._names.add(self.name)
 
     @property
     def tag(self) -> str:
@@ -44,6 +52,11 @@ class JsComponent(Component):
 class Resource:
     key: str
     path: Path
+    _keys: ClassVar[set[str]] = set()
+
+    def __post_init__(self) -> None:
+        assert self.key not in self._keys, f'Duplicate key "{self.key}" for {self.__class__.__name__} {self.path}'
+        self._keys.add(self.key)
 
 
 @dataclass(**KWONLY_SLOTS)
@@ -53,16 +66,29 @@ class DynamicResource:
 
 
 @dataclass(**KWONLY_SLOTS)
-class Library:
-    key: str
+class Import:
     name: str
     path: Path
+    _names: ClassVar[set[str]] = set()
+
+    def __post_init__(self) -> None:
+        assert self.name not in self._names, f'Duplicate name "{self.name}" for {self.__class__.__name__} {self.path}'
+        self._names.add(self.name)
 
 
 @dataclass(**KWONLY_SLOTS)
-class EsmModule:
-    name: str
-    path: Path
+class Library(Import):
+    key: str
+    _keys: ClassVar[set[str]] = set()
+
+    def __post_init__(self) -> None:
+        assert self.key not in self._keys, f'Duplicate key "{self.key}" for {self.__class__.__name__} {self.path}'
+        self._keys.add(self.key)
+
+
+@dataclass(**KWONLY_SLOTS)
+class EsmModule(Import):
+    pass
 
 
 vue_components: dict[str, VueComponent] = {}
@@ -85,14 +111,12 @@ def register_vue_component(path: Path, *, max_time: float | None) -> Component:
     if path.suffix == '.vue':
         if key in vue_components and vue_components[key].path == path:
             return vue_components[key]
-        assert key not in vue_components, f'Duplicate VUE component {key}'
         v = VBuild(path)
         vue_components[key] = VueComponent(key=key, name=name, path=path, html=v.html, script=v.script, style=v.style)
         return vue_components[key]
     if path.suffix == '.js':
         if key in js_components and js_components[key].path == path:
             return js_components[key]
-        assert key not in js_components, f'Duplicate JS component {key}'
         js_components[key] = JsComponent(key=key, name=name, path=path)
         return js_components[key]
     raise ValueError(f'Unsupported component type "{path.suffix}"')
@@ -105,7 +129,6 @@ def register_library(path: Path, *, max_time: float | None) -> Library:
     if path.suffix in {'.js', '.mjs'}:
         if key in libraries and libraries[key].path == path:
             return libraries[key]
-        assert key not in libraries, f'Duplicate js library {key}'
         libraries[key] = Library(key=key, name=name, path=path)
         return libraries[key]
     raise ValueError(f'Unsupported library type "{path.suffix}"')
@@ -116,7 +139,6 @@ def register_resource(path: Path, *, max_time: float | None) -> Resource:
     key = compute_key(path, max_time=max_time)
     if key in resources and resources[key].path == path:
         return resources[key]
-    assert key not in resources, f'Duplicate resource {key}'
     resources[key] = Resource(key=key, path=path)
     return resources[key]
 
@@ -129,8 +151,6 @@ def register_dynamic_resource(name: str, function: Callable) -> DynamicResource:
 
 def register_esm(name: str, path: Path, *, max_time: float | None) -> None:
     """Register an ESM module."""
-    if any(name == esm_module.name for esm_module in esm_modules.values()):
-        raise ValueError(f'Duplicate ESM module name "{name}"')
     esm_modules[compute_key(path, max_time=max_time)] = EsmModule(name=name, path=path)
 
 
@@ -172,7 +192,7 @@ def generate_resources(prefix: str, elements: Iterable[Element]) -> tuple[list[s
         'immutable': f'{prefix}/_nicegui/{__version__}/static/immutable.es.js',
     }
     js_imports: list[str] = []
-    js_imports_urls: list[str] = []
+    js_imports_urls: list[str] = [imports['vue']]
 
     # build the importmap structure for libraries
     for key, library in libraries.items():

{nicegui-3.4.0 → nicegui-3.5.0}/nicegui/element.py

@@ -86,6 +86,9 @@ class Element(Visibility):
         if self._parent_slot:
             client.outbox.enqueue_update(parent_slot.parent)
 
+        self._props.add_rename('resource_path', 'resource-path')  # DEPRECATED: remove in NiceGUI 4.0
+        self._props.add_rename('dynamic_resource_path', 'dynamic-resource-path')  # DEPRECATED: remove in NiceGUI 4.0
+
     def __init_subclass__(cls, *,
                           component: str | Path | None = None,
                           dependencies: list[str | Path] = [],  # noqa: B006
@@ -156,7 +159,7 @@ class Element(Visibility):
         """
         path_ = Path(path)
         resource = register_resource(path_, max_time=path_.stat().st_mtime)
-        self._props['resource_path'] = f'/_nicegui/{__version__}/resources/{resource.key}'
+        self._props['resource-path'] = f'/_nicegui/{__version__}/resources/{resource.key}'
 
     def add_dynamic_resource(self, name: str, function: Callable) -> None:
         """Add a dynamic resource to the element which returns the result of a function.
@@ -165,7 +168,7 @@ class Element(Visibility):
         :param function: function that returns the resource response
         """
         register_dynamic_resource(name, function)
-        self._props['dynamic_resource_path'] = f'/_nicegui/{__version__}/dynamic_resources'
+        self._props['dynamic-resource-path'] = f'/_nicegui/{__version__}/dynamic_resources'
 
     def add_slot(self, name: str, template: str | None = None) -> Slot:
         """Add a slot to the element.
@@ -533,7 +536,7 @@ class Element(Visibility):
             additions.append(f'text={shorten(self._text)}')
         if hasattr(self, 'content') and self.content:  # pylint: disable=no-member
             additions.append(f'content={shorten(self.content)}')  # pylint: disable=no-member
-        IGNORED_PROPS = {'loopback', 'color', 'view', 'innerHTML', 'dynamic_resource_path'}
+        IGNORED_PROPS = {'loopback', 'color', 'view', 'innerHTML', 'dynamic-resource-path'}
         additions += [
             f'{key}={shorten(value)}'
             for key, value in self._props.items()

{nicegui-3.4.0 → nicegui-3.5.0}/nicegui/elements/aggrid/aggrid.js

@@ -23,7 +23,7 @@ export default {
         theme: AgGrid.themes[this.options.theme].withPart(AgGrid.colorSchemeVariable),
       };
 
-      for (const column of this.html_columns) {
+      for (const column of this.htmlColumns) {
         if (this.gridOptions.columnDefs[column].cellRenderer === undefined) {
           this.gridOptions.columnDefs[column].cellRenderer = (params) => (params.value ? params.value : "");
         }
@@ -111,6 +111,6 @@ export default {
   },
   props: {
     options: Object,
-    html_columns: Array,
+    htmlColumns: Array,
   },
 };

{nicegui-3.4.0 → nicegui-3.5.0}/nicegui/elements/aggrid/aggrid.py

@@ -5,6 +5,7 @@ from typing_extensions import Self
 
 from ... import optional_features
 from ...awaitable_response import AwaitableResponse
+from ...defaults import DEFAULT_PROP, resolve_defaults
 from ...element import Element
 
 if importlib.util.find_spec('pandas'):
@@ -20,9 +21,10 @@ if importlib.util.find_spec('polars'):
 
 class AgGrid(Element, component='aggrid.js', esm={'nicegui-aggrid': 'dist'}, default_classes='nicegui-aggrid'):
 
+    @resolve_defaults
     def __init__(self,
                  options: dict, *,
-                 html_columns: list[int] = [],  # noqa: B006
+                 html_columns: list[int] = DEFAULT_PROP | [],
                  theme: Optional[Literal['quartz', 'balham', 'material', 'alpine']] = None,
                  auto_size_columns: bool = True,
                  ) -> None:
@@ -44,9 +46,11 @@ class AgGrid(Element, component='aggrid.js', esm={'nicegui-aggrid': 'dist'}, def
             **({'autoSizeStrategy': {'type': 'fitGridWidth'}} if auto_size_columns else {}),
             **options,
         }
-        self._props['html_columns'] = html_columns[:]
+        self._props['html-columns'] = html_columns[:]
         self._update_method = 'update_grid'
 
+        self._props.add_rename('html_columns', 'html-columns')  # DEPRECATED: remove in NiceGUI 4.0
+
     @classmethod
     def from_pandas(cls,
                     df: 'pd.DataFrame', *,
@@ -135,11 +139,11 @@ class AgGrid(Element, component='aggrid.js', esm={'nicegui-aggrid': 'dist'}, def
     @property
     def html_columns(self) -> list[int]:
         """The list of columns that should be rendered as HTML."""
-        return self._props['html_columns']
+        return self._props['html-columns']
 
     @html_columns.setter
     def html_columns(self, value: list[int]) -> None:
-        self._props['html_columns'] = value[:]
+        self._props['html-columns'] = value[:]
 
     @property
     def theme(self) -> Optional[Literal['quartz', 'balham', 'material', 'alpine']]:

nicegui-3.5.0/nicegui/elements/altair.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import importlib.util
+from typing import TYPE_CHECKING
+
+from .. import optional_features
+from .anywidget import AnyWidget
+
+if importlib.util.find_spec('altair'):
+    optional_features.register('altair')
+    if TYPE_CHECKING:
+        import altair
+
+
+class Altair(AnyWidget):
+
+    def __init__(self, chart: altair.Chart | altair.JupyterChart, *, throttle: float = 0) -> None:
+        """Altair Chart
+
+        Wrap an ``altair.Chart`` or ``altair.JupyterChart`` in NiceGUI via anywidget.
+
+        Refer to the `altair documentation <https://altair-viz.github.io/user_guide/interactions/jupyter_chart.html#accessing-variable-params>`_
+        for more information about synchronizing Altair parameters with Python.
+
+        *Added in version 3.5.0*
+
+        :param chart: the ``altair.Chart`` or ``altair.JupyterChart`` to wrap
+        :param throttle: minimum time (in seconds) between widget updates to Python (default: 0.0)
+        """
+        import altair  # pylint: disable=import-outside-toplevel
+
+        if isinstance(chart, altair.Chart):
+            chart = altair.JupyterChart(chart)
+
+        super().__init__(chart, throttle=throttle)  # type: ignore[arg-type]

nicegui-3.5.0/nicegui/elements/anywidget/__init__.py

@@ -0,0 +1,3 @@
+from .anywidget import AnyWidget
+
+__all__ = ['AnyWidget']

nicegui-3.5.0/nicegui/elements/anywidget/anywidget.js

@@ -0,0 +1,64 @@
+import { load_widget, load_css } from "widget";
+import { cleanObject } from "../../static/utils/json.js";
+
+export default {
+  template: "<div></div>",
+  async mounted() {
+    const emit_to_py = this.$emit;
+
+    // Implement AFM: https://anywidget.dev/en/afm/
+    // References:
+    // * Marimo AFM impl:
+    // https://github.com/marimo-team/marimo/blob/7f3023ff0caef22b2bf4c1b5a18ad1899bd40fa3/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx#L161-L267
+    this.model = {
+      attributes: { ...this.traits },
+      callbacks: {},
+      get: function (key) {
+        return cleanObject(this.attributes[key]);
+      },
+      set: function (key, value) {
+        this.attributes[key] = value;
+        this.emit("change:" + key, value);
+      },
+      save_changes: function () {
+        if (this.callbacks.change && Array.isArray(this.callbacks.change)) {
+          this.callbacks.change.forEach((cb) => cb());
+        }
+        emit_to_py("update:traits", { ...this.attributes });
+      },
+      on: function (event, callback) {
+        if (!this.callbacks[event]) this.callbacks[event] = [];
+        this.callbacks[event].push(callback);
+      },
+      off: function (event, callback) {
+        if (!event) this.callbacks = {};
+        else if (!callback) this.callbacks[event] = [];
+        else this.callbacks[event]?.delete(callback);
+      },
+      emit: function (event, value) {
+        this.callbacks[event]?.forEach((cb) => cb(value));
+      },
+      send: function (content, callbacks, buffers) {
+        console.warn("anywidget.send() is not yet implemented in NiceGUI", content);
+      },
+    };
+
+    // Dynamically load esm_content as an ECMAScript module
+    const mod = await load_widget(this.esm_content, this.traits._anywidget_id);
+    // TODO: cleanup_widget and cleanup_view should be called when the widget is destroyed
+    this.cleanup_widget = await mod.initialize?.({ model: this.model });
+    this.cleanup_view = await mod.render?.({ model: this.model, el: this.$el });
+
+    load_css(this.css_content, this.traits._anywidget_id);
+  },
+  methods: {
+    update_trait(trait, value) {
+      this.model.set(trait, value);
+    },
+  },
+  props: {
+    traits: Object,
+    esm_content: String,
+    css_content: String,
+  },
+};

nicegui-3.5.0/nicegui/elements/anywidget/anywidget.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import importlib.util
+import inspect
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ... import helpers, optional_features
+from ..mixins.value_element import ValueElement
+
+if importlib.util.find_spec('anywidget'):
+    optional_features.register('anywidget')
+    if TYPE_CHECKING:
+        import anywidget
+
+
+class AnyWidget(ValueElement, component='anywidget.js', dependencies=['lib/widget.js']):
+    VALUE_PROP: str = 'traits'
+
+    def __init__(self, widget: anywidget.AnyWidget, *, throttle: float = 0) -> None:
+        """AnyWidget
+
+        `anywidget <https://anywidget.dev/en/getting-started/>`_ is a library that allows you to
+        embed arbitrary JavaScript widgets in a cross-frontend friendly manner.
+
+        There are many publicly available examples of anywidget widgets
+        in the `anywidget gallery <https://try.anywidget.dev/>`_, including
+        `altair.JupyterChart <https://altair-viz.github.io/user_guide/interactions/jupyter_chart.html>`_,
+        and `quak <https://github.com/manzt/quak>`_.
+
+        Implementation: The ``nicegui.anywidget`` element takes an ``AnyWidget`` and observes all ``sync=True`` traits
+        of the widget, trigger JS updates when the traits change.
+        Conversely, changes on the frontend will be synced back to the widget,
+        using ``ValueElement``'s handling to listen to changes on ``traits``.
+
+        *Added in version 3.5.0*
+
+        :param widget: the ``anywidget.AnyWidget`` to wrap
+        :param throttle: minimum time (in seconds) between widget updates to Python (default: 0.0)
+        """
+        self._widget = widget
+        self._traits = widget.traits(sync=True)
+        super().__init__(value=widget.get_state(self._traits), throttle=throttle)
+        self._props['esm_content'] = _get_attribute(widget, '_esm')
+        self._props['css_content'] = _get_attribute(widget, '_css')
+        self._run_update_traits = True
+
+        def observe_change(change) -> None:
+            if self._run_update_traits:
+                self.run_method('update_trait', change['name'], change['new'])
+        widget.observe(observe_change, self._traits)
+
+    def _handle_value_change(self, value: Any) -> None:
+        """Update the widget's state when the value changes from frontend"""
+        self._run_update_traits = False
+        try:
+            super()._handle_value_change(value)
+            state = self._widget.get_state(self._traits)
+            for key, value_ in value.items():
+                if state[key] != value_:
+                    setattr(self._widget, key, value_)
+        finally:
+            self._run_update_traits = True
+
+
+def _get_attribute(obj: object, name: str) -> str:
+    """Extract the attribute's content, reading if it is a path to a file."""
+    content = getattr(obj, name, '')
+    if callable(content) and not inspect.isclass(content):  # content is a property function
+        content = content()
+    assert isinstance(content, (str, Path)), f'Attribute {name} is not a string or Path'
+    if helpers.is_file(content):
+        content = Path(content).read_text(encoding='utf8')
+    assert isinstance(content, str), f'Attribute {name} is a Path but does not exist'
+    return content