instaui 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

instaui/static/templates/web.html

@@ -46,7 +46,7 @@
 
   <script type="module">
     import { createApp } from 'vue'
-    import installInsta from 'instaui'
+    import {install as installInsta} from 'instaui'
     const True = true;
     const False = false;
     const None = undefined;

instaui/static/templates/webview.html

@@ -43,7 +43,7 @@
 
   <script type="module">
     import { createApp } from 'vue'
-    import installInsta from 'instaui'
+    import {install as installInsta} from 'instaui'
     const True = true;
     const False = false;
     const None = undefined;

instaui/static/templates/zero.html

@@ -43,7 +43,7 @@
 
   <script type="module">
     import { createApp } from 'vue'
-    import installInsta from 'instaui'
+    import {install as installInsta} from 'instaui'
     const True = true;
     const False = false;
     const None = undefined;

instaui/systems/func_system.py

@@ -35,6 +35,21 @@ def get_fn_params_infos(fn: Callable) -> List[Tuple[str, type]]:
     ]
 
 
+def is_last_param_args(fn):
+    """
+    Returns:
+        bool: True if the last parameter of the function is `*args`, False otherwise.
+    """
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+
+    if not params:
+        return False
+
+    last_param = params[-1]
+    return last_param.kind == inspect.Parameter.VAR_POSITIONAL
+
+
 def get_required_param_count(fn: Callable):
     signature = inspect.signature(fn)
     params = signature.parameters

instaui/ui/__init__.py

@@ -29,6 +29,7 @@ __all__ = [
     "element",
     "vfor",
     "content",
+    "label",
     "add_style",
     "add_css_link",
     "remove_css_link",
@@ -42,6 +43,7 @@ __all__ = [
     "page",
     "event",
     "js_event",
+    "vue_event",
     "event_context",
     "TEventFn",
     "server",
@@ -103,9 +105,11 @@ from instaui.components.vfor import VFor as vfor
 from instaui.components.vif import VIf as vif
 from instaui.components.match import Match as match
 from instaui.components.content import Content as content
+from instaui.components.label import label
 
-from instaui.event.web_event import ui_event as event, WebEvent as TEventFn
+from instaui.event.web_event import event, WebEvent as TEventFn
 from instaui.event.js_event import js_event
+from instaui.event.vue_event import vue_event
 from instaui.vars.event_context import EventContext as event_context
 from instaui.runtime.context import get_context as context
 

instaui/ui/__init__.pyi

@@ -29,6 +29,7 @@ __all__ = [
     "element",
     "vfor",
     "content",
+    "label",
     "add_style",
     "add_css_link",
     "remove_css_link",
@@ -42,6 +43,7 @@ __all__ = [
     "page",
     "event",
     "js_event",
+    "vue_event",
     "event_context",
     "TEventFn",
     "server",
@@ -103,9 +105,11 @@ from instaui.components.vfor import VFor as vfor
 from instaui.components.vif import VIf as vif
 from instaui.components.match import Match as match
 from instaui.components.content import Content as content
+from instaui.components.label import label
 
-from instaui.event.web_event import ui_event as event, WebEvent as TEventFn
+from instaui.event.web_event import event, WebEvent as TEventFn
 from instaui.event.js_event import js_event
+from instaui.event.vue_event import vue_event
 from instaui.vars.event_context import EventContext as event_context
 from instaui.runtime.context import get_context as context
 

instaui/ui_functions/ui_page.py

@@ -2,15 +2,15 @@ from typing import Callable
 from instaui.launch_collector import get_launch_collector, PageInfo
 
 
-def page(url: str = "/"):
+def page(path: str = "/"):
     """Register a page route.
 
     Args:
-        url (str): The route URL.
+        path (str): The route path.
     """
 
     def wrapper(func: Callable):
-        get_launch_collector().register_page(PageInfo(url, func))
+        get_launch_collector().register_page(PageInfo(path, func))
         return func
 
     return wrapper

instaui/vars/js_computed.py

@@ -25,14 +25,34 @@ class JsComputed(
     StrFormatBindingMixin,
     ElementBindingMixin,
 ):
+    """
+    A client-side computed property that evaluates JavaScript code to derive reactive values.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence[TObservableInput]], optional): Reactive data sources to monitor.
+                                                  Changes to these values trigger re-computation.
+        code (str): JavaScript code to execute for computing the value.
+        async_init_value (typing.Optional[typing.Any], optional): Initial value to use before first successful async evaluation.
+
+    # Example:
+    .. code-block:: python
+        a = ui.state(0)
+
+        plus_one = ui.js_computed(inputs=[a], code="a=> a+1")
+
+        html.number(a)
+        ui.label(plus_one)
+    """
+
     BIND_TYPE = "var"
 
     def __init__(
         self,
         *,
         inputs: typing.Optional[typing.Sequence[TObservableInput]] = None,
-        code: str = "",
+        code: str,
         async_init_value: typing.Optional[typing.Any] = None,
+        deep_compare_on_input: bool = False,
     ) -> None:
         self.code = code
 
@@ -46,6 +66,7 @@ class JsComputed(
         )
 
         self._async_init_value = async_init_value
+        self._deep_compare_on_input = deep_compare_on_input
 
     def __to_binding_config(self):
         return {
@@ -87,6 +108,9 @@ class JsComputed(
         if self._async_init_value is not None:
             data["asyncInit"] = self._async_init_value
 
+        if self._deep_compare_on_input is not False:
+            data["deepEqOnInput"] = 1
+
         return data
 
 

instaui/vars/state.py

@@ -78,5 +78,20 @@ class StateModel(BaseModel, Jsonable):
 
 
 def state(value: _T) -> _T:
+    """
+    Creates a reactive state object that tracks changes and notifies dependencies.
+
+    Args:
+        value (_T): The initial value to wrap in a reactive state container.
+                   Can be any type (primitive, object, or complex data structure).
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui,html
+        count = ui.state(0)
+
+        html.number(count)
+        ui.label(count)
+    """
     obj = RefProxy(_ProxyModel(value))  # type: ignore
     return obj  # type: ignore

instaui/vars/web_computed.py

@@ -50,6 +50,7 @@ class WebComputed(
         extend_outputs: Optional[Sequence[CanOutputMixin]] = None,
         init_value: Optional[R] = None,
         evaluating: Optional[CanOutputMixin] = None,
+        deep_compare_on_input: bool = False,
         debug_info: Optional[Dict] = None,
     ) -> None:
         scope = get_current_scope()
@@ -65,6 +66,7 @@ class WebComputed(
         self._fn = func
         self._init_value = init_value
         self._evaluating = evaluating
+        self._deep_compare_on_input = deep_compare_on_input
 
         if debug_info is not None:
             self.debug = debug_info
@@ -111,6 +113,9 @@ class WebComputed(
         if self._evaluating:
             data["running"] = self._evaluating._to_output_config()
 
+        if self._deep_compare_on_input is not False:
+            data["deepEqOnInput"] = 1
+
         return data
 
         # return {}
@@ -144,8 +149,38 @@ def web_computed(
     extend_outputs: Optional[Sequence] = None,
     init_value: Optional[Any] = None,
     evaluating: Optional[Any] = None,
+    deep_compare_on_input: bool = False,
     debug_info: Optional[Dict] = None,
 ):
+    """
+    Creates a computed property decorator for reactive programming with dependency tracking.
+
+    This decorator factory wraps functions to create reactive computed properties that:
+    - Automatically re-evaluate when dependencies (inputs) change
+    - Cache results for performance optimization
+    - Support both synchronous and asynchronous computation patterns
+
+    Args:
+        inputs (Optional[Sequence], optional): Collection of reactive sources that trigger recomputation
+                                   when changed. These can be state objects or other computed properties.
+        extend_outputs (Optional[Sequence], optional):  Additional outputs to notify when this computed value updates.
+        init_value (Optional[Any], optional): Initial value to return before first successful evaluation.
+        evaluating (Optional[Any], optional): Temporary value returned during asynchronous computation.
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui,html
+
+        a = ui.state(0)
+
+        @ui.computed(inputs=[a])
+        def plus_one(a):
+            return a + 1
+
+        html.number(a)
+        ui.label(plus_one)
+    """
+
     def wrapper(func: Callable[P, R]):
         return WebComputed(
             func,
@@ -153,6 +188,7 @@ def web_computed(
             extend_outputs=extend_outputs,
             init_value=init_value,
             evaluating=evaluating,
+            deep_compare_on_input=deep_compare_on_input,
             debug_info=debug_info,
         )
 

instaui/watch/js_watch.py

@@ -21,6 +21,8 @@ class JsWatch(Jsonable):
         once: bool = False,
         flush: typing.Optional[_types.TFlush] = None,
     ) -> None:
+        inputs = observable_helper.auto_made_inputs_to_slient(inputs, outputs)
+
         get_current_scope().register_js_watch(self)
 
         self.code = code
@@ -65,10 +67,44 @@ def js_watch(
     *,
     inputs: typing.Optional[typing.Sequence] = None,
     outputs: typing.Optional[typing.Sequence] = None,
-    code: str = "",
+    code: str,
     immediate: bool = True,
     deep: typing.Union[bool, int] = False,
     once: bool = False,
     flush: typing.Optional[_types.TFlush] = None,
 ):
+    """
+    Creates a client-side observer that executes JavaScript code in response to reactive source changes.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional): Reactive sources to observe. Changes to these sources
+                                   trigger the watcher's JavaScript execution.
+        outputs (typing.Optional[typing.Sequence], optional): Output targets associated with this watcher. Used for
+                                    coordination with other observers.
+        code (str, optional): JavaScript code to execute when changes are detected. The code has access
+                  to the current values of observed inputs through the `args` parameter.
+        immediate (bool, optional):If True, executes the watcher immediately after creation with current values. Defaults to True.
+        deep (typing.Union[bool, int], optional): Controls depth of change detection:
+                               - True: Recursively tracks nested properties
+                               - False: Shallow comparison only
+                               - int: Maximum depth level to track (for complex objects).
+                               Defaults to False.
+        once (bool, optional): If True, automatically stops observation after first trigger. Defaults to False.
+        flush (typing.Optional[_types.TFlush], optional): Controls when to flush updates:
+                                      - 'sync': Execute immediately on change
+                                      - 'post': Batch updates and execute after current tick
+                                      - 'pre': Execute before render phase (if applicable)
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state('')
+        ui.js_watch(inputs=[num], outputs=[msg], code="num => `The number is ${num}`")
+
+        html.number(num)
+        ui.label(msg)
+    """
+
     return JsWatch(code, inputs, outputs, immediate, deep, once, flush)

instaui/watch/web_watch.py

@@ -32,6 +32,8 @@ class WebWatch(Jsonable, typing.Generic[P, R]):
         flush: typing.Optional[_types.TFlush] = None,
         _debug: typing.Optional[typing.Any] = None,
     ) -> None:
+        inputs = observable_helper.auto_made_inputs_to_slient(inputs, outputs)
+
         get_current_scope().register_web_watch(self)
 
         self._inputs, self._is_slient_inputs, self._is_data = (
@@ -107,6 +109,57 @@ def watch(
     flush: typing.Optional[_types.TFlush] = None,
     _debug: typing.Optional[typing.Any] = None,
 ):
+    """
+    Creates an observer that tracks changes in reactive sources and triggers callbacks.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional): Reactive sources to observe (state objects or computed properties).
+                                   Changes to these sources trigger the watcher callback.
+        outputs (typing.Optional[typing.Sequence], optional): Output targets associated with this watcher.
+                                    Used for coordination with computed properties or other observers.
+        immediate (bool, optional): If True, executes callback immediately after creation with current values. Defaults to True.
+        deep (typing.Union[bool, int], optional): Controls depth of change detection:
+                               - True: Recursively tracks nested properties
+                               - False: Shallow comparison only
+                               - int: Maximum depth level to track (for complex objects).
+                               Defaults to True.
+        once (bool, optional):  If True, automatically stops observation after first trigger. Defaults to False.
+        flush (typing.Optional[_types.TFlush], optional): Controls when to flush updates:
+                                      - 'sync': Execute immediately on change
+                                      - 'post': Batch updates and execute after current tick
+                                      - 'pre': Execute before render phase (if applicable)
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state('')
+
+        @ui.watch(inputs=[num], outputs=[msg])
+        def when_num_change(num):
+            return f"The number is {num}"
+
+        html.number(num)
+        ui.label(msg)
+
+    list append:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state([])
+
+        @ui.watch(inputs=[num, msg], outputs=[msg])
+        def when_num_change(num, msg:list):
+            msg.append(f"The number changed to {num}")
+            return msg
+
+        html.number(num)
+        ui.label(msg)
+
+    """
+
     def wrapper(func: typing.Callable[P, R]):
         return WebWatch(
             func,

instaui-0.1.11.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: instaui
+Version: 0.1.11
+Summary: insta-ui is a Python-based UI library for rapidly building user interfaces.
+Author-email: CrystalWindSnake <568166495@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gui,ui,web
+Requires-Python: <3.13,>=3.8
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: orjson>=3.10.15
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: typing-extensions>=4.13.2
+Provides-Extra: all
+Requires-Dist: fastapi[standard]; extra == 'all'
+Requires-Dist: pywebview; extra == 'all'
+Requires-Dist: uvicorn; extra == 'all'
+Provides-Extra: web
+Requires-Dist: fastapi[standard]; extra == 'web'
+Requires-Dist: pydantic<3.0.0,>=2.10.6; extra == 'web'
+Requires-Dist: uvicorn; extra == 'web'
+Provides-Extra: webview
+Requires-Dist: pydantic<3.0.0,>=2.10.6; extra == 'webview'
+Requires-Dist: pywebview; extra == 'webview'
+Description-Content-Type: text/markdown
+
+# insta-ui
+
+<div align="center">
+
+English| [简体中文](./README.md)
+
+</div>
+
+## 📖 Introduction
+insta-ui is a Python-based UI library for quickly building user interfaces.
+
+## ⚙️ Features
+Three modes:
+
+- Web mode: Generate web (stateless) applications.
+- Web View mode: Generate web view applications that can be packaged as native apps (no need to start a web server).
+- Zero mode: Generate pure HTML files that run directly in browsers without any dependencies.
+
+ 
+## 📦 Installation
+
+Zero mode:
+
+```
+pip install instaui -U
+```
+
+web mode
+
+```
+pip install instaui[web] -U
+```
+
+Web View mode
+```
+pip install instaui[webview] -U
+```
+
+
+## 🖥️ Quick Start
+Below is a simple example of number summation. The result color changes dynamically based on the sum:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    # Automatically recalculates result when num1 or num2 changes 
+    @ui.computed(inputs=[num1, num2])
+    def result(num1: int, num2: int):
+        return num1 + num2
+
+    # Automatically updates text_color when result changes
+    @ui.computed(inputs=[result])
+    def text_color(result: int):
+        return "red" if result % 2 == 0 else "blue"
+
+    # UI components  
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+ui.server().run()
+```
+
+Replace `ui.server().run()` with `ui.webview().run()` to switch to Web View mode:
+
+```python
+...
+
+# ui.server().run()
+ui.webview().run()
+```
+
+To execute computations on the client side instead of the server, use `ui.js_computed` instead of `ui.computed`:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    ...
+
+...
+
+```
+
+In this case, all interactions will run on the client side. Use `Zero mode` to generate a standalone HTML file:
+
+```python
+from instaui import ui, arco,zero
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+with zero() as z:
+    home()
+    z.to_html('index.html')
+
+```