htag 2.0.7__tar.gz → 2.0.9__tar.gz

{htag-2.0.7 → htag-2.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htag
-Version: 2.0.7
+Version: 2.0.9
 Summary: Python3 GUI toolkit for building 'beautiful' applications for mobile, web, and desktop from a single codebase
 Author: manatlan
 License: MIT
@@ -101,6 +101,7 @@ htag is a Python library for building web applications using HTML, CSS, and Java
 *   **HTTP Fallback (SSE + POST)**: If WebSockets are blocked (e.g. strict proxies) or fail to connect, the client seamlessly falls back to HTTP POST for events and Server-Sent Events (SSE) for receiving UI updates.
 *   **Production Debug Mode**: Easily disable error reporting in the client by setting `debug=False` on the runner (e.g. `WebApp(App, debug=False).app`), preventing internal stacktraces from leaking to users.
 *   **Parano Mode (Payload Obfuscation)**: By initializing `WebApp(App, parano=True)`, all data exchanged between the frontend and backend is automatically obfuscated using a dynamic XOR cipher and Base64 wrapping, making network traffic unreadable to MITM proxies.
+*   **Progressive UI in Lifecycle Hooks**: Both `on_mount()` and `on_unmount()` fully support yielding intermediate UI states natively. `htag` intelligently queues `on_mount` generators until the client establishes a connection, and gracefully processes `on_unmount` broadcasts.
 *   **`.root`, `.parent`, and `.childs` properties**: Every `GTag` exposes its position in the component tree. `.root` references the main `Tag` instance, `.parent` references the direct parent component, and `.childs` is a list of its children. This allows components to easily navigate the DOM tree and trigger app-level actions.
 *   **Declarative UI with Context Managers (`with`)**: You can now build component trees visually using `with` blocks (e.g., `with Tag.div(): Tag.h1("Hello")`), removing the need for `self <= ...` boilerplate.
 *   **Modern Attribute Access (Dictionary Style)**: In addition to `Tag.div(_class="foo")` in constructors, you must now use `self["class"] = "foo"` for dynamic property management after instantiation. This is the only way to handle all attributes, including those with dashes (e.g., `self["data-id"] = 123`).

{htag-2.0.7 → htag-2.0.9}/README.md

@@ -80,6 +80,7 @@ htag is a Python library for building web applications using HTML, CSS, and Java
 *   **HTTP Fallback (SSE + POST)**: If WebSockets are blocked (e.g. strict proxies) or fail to connect, the client seamlessly falls back to HTTP POST for events and Server-Sent Events (SSE) for receiving UI updates.
 *   **Production Debug Mode**: Easily disable error reporting in the client by setting `debug=False` on the runner (e.g. `WebApp(App, debug=False).app`), preventing internal stacktraces from leaking to users.
 *   **Parano Mode (Payload Obfuscation)**: By initializing `WebApp(App, parano=True)`, all data exchanged between the frontend and backend is automatically obfuscated using a dynamic XOR cipher and Base64 wrapping, making network traffic unreadable to MITM proxies.
+*   **Progressive UI in Lifecycle Hooks**: Both `on_mount()` and `on_unmount()` fully support yielding intermediate UI states natively. `htag` intelligently queues `on_mount` generators until the client establishes a connection, and gracefully processes `on_unmount` broadcasts.
 *   **`.root`, `.parent`, and `.childs` properties**: Every `GTag` exposes its position in the component tree. `.root` references the main `Tag` instance, `.parent` references the direct parent component, and `.childs` is a list of its children. This allows components to easily navigate the DOM tree and trigger app-level actions.
 *   **Declarative UI with Context Managers (`with`)**: You can now build component trees visually using `with` blocks (e.g., `with Tag.div(): Tag.h1("Hello")`), removing the need for `self <= ...` boilerplate.
 *   **Modern Attribute Access (Dictionary Style)**: In addition to `Tag.div(_class="foo")` in constructors, you must now use `self["class"] = "foo"` for dynamic property management after instantiation. This is the only way to handle all attributes, including those with dashes (e.g., `self["data-id"] = 123`).

{htag-2.0.7 → htag-2.0.9}/htag/core.py

@@ -392,8 +392,8 @@ class GTag:  # aka "Generic Tag"
         # Always append htag's internal unique ID as 'data-htag-id' or just 'id' if not already present
         if "id" not in self.__attrs:
             attrs += f' id="{self.id}"'
-        else:
-            # If user provided a custom ID, we still need htag id for event mapping
+        elif str(self.__attrs["id"]) != self.id:
+            # If user provided a custom ID different from htag internal ID, we still need htag id for event mapping
             attrs += f' data-htag-id="{self.id}"'
         return attrs
 
@@ -440,6 +440,8 @@ class GTag:  # aka "Generic Tag"
 
         if getattr(self, "tag", None) in ("style", "script"):
             self.id = ""
+        elif "_id" in kwargs:
+            self.id = str(kwargs["_id"])
         else:
             self.id = f"{self.tag}-{id(self)}"
         logger.debug("Created Tag: %s (id: %s)", self.tag, self.id)
@@ -503,7 +505,16 @@ class GTag:  # aka "Generic Tag"
         pass
 
     def _trigger_mount(self) -> None:
-        self.on_mount()
+        import inspect
+        res = self.on_mount()
+        if inspect.isgenerator(res) or inspect.isasyncgen(res):
+            root = self.root
+            if root is not None and type(root).__name__ != "GTag":
+                # Only root representing the application
+                if not hasattr(root, "_pending_lifecycle_generators"):
+                    root._pending_lifecycle_generators = []
+                root._pending_lifecycle_generators.append((self, res))
+
         for child in self.childs:
             if isinstance(child, GTag):
                 child._trigger_mount()
@@ -512,7 +523,16 @@ class GTag:  # aka "Generic Tag"
                 t._trigger_mount()
 
     def _trigger_unmount(self) -> None:
-        self.on_unmount()
+        import inspect
+        res = self.on_unmount()
+        if inspect.isgenerator(res) or inspect.isasyncgen(res):
+            root = self.root
+            if root is not None and type(root).__name__ != "GTag":
+                # Only root representing the application
+                if not hasattr(root, "_pending_lifecycle_generators"):
+                    root._pending_lifecycle_generators = []
+                root._pending_lifecycle_generators.append((self, res))
+
         for child in self.childs:
             if isinstance(child, GTag):
                 child._trigger_unmount()

{htag-2.0.7 → htag-2.0.9}/htag/runner.py

@@ -182,7 +182,9 @@ class AppRunner(BaseApp):
         <!DOCTYPE html>
         <html>
             <head>
+                <meta charset="utf-8">
                 <title>{self.__class__.__name__}</title>
+                <meta name="viewport" content="width=device-width, initial-scale=1">
                 <link rel="icon" href="/logo.png">
                 <script>{CLIENT_JS}</script>
                 <script>
@@ -217,6 +219,7 @@ class AppRunner(BaseApp):
             payload_str = self._build_initial_payload()
             # EventSource requires 'data: {payload}\n\n'
             yield f"data: {payload_str}\n\n"
+            self._flush_pending_lifecycle_generators(None)
         except Exception as e:
             logger.error("Failed to send initial SSE state: %s", e)
 
@@ -246,6 +249,7 @@ class AppRunner(BaseApp):
             payload_str = self._build_initial_payload()
             await websocket.send_text(payload_str)
             logger.debug("Sent initial state to client")
+            self._flush_pending_lifecycle_generators(websocket)
         except Exception as e:
             logger.error("Failed to send initial state: %s", e)
 
@@ -464,6 +468,51 @@ class AppRunner(BaseApp):
             if callback_id:
                 await self.broadcast_updates(result=None, callback_id=callback_id, ws=ws)
 
+        self._flush_pending_lifecycle_generators(ws)
+
+    def _flush_pending_lifecycle_generators(self, ws: WebSocket | None = None) -> None:
+        if hasattr(self, "_pending_lifecycle_generators") and self._pending_lifecycle_generators:
+            while self._pending_lifecycle_generators:
+                tag, gen = self._pending_lifecycle_generators.pop(0)
+                asyncio.create_task(self._consume_generator(gen, ws))
+
+    async def _consume_generator(self, gen: Any, ws: WebSocket | None = None) -> None:
+        try:
+            if inspect.isasyncgen(gen):
+                async for _ in gen:
+                    await self.broadcast_updates(ws=ws)
+            elif inspect.isgenerator(gen):
+                try:
+                    while True:
+                        next(gen)
+                        await self.broadcast_updates(ws=ws)
+                except StopIteration:
+                    pass
+        except Exception as e:
+            error_trace: str = traceback.format_exc()
+            error_msg: str = f"Error in on_mount generator: {str(e)}\n{error_trace}"
+            print(error_msg)
+            logger.error(error_msg)
+            err_payload: str = _obf_dumps(
+                {
+                    "action": "error",
+                    "traceback": error_trace if self.debug else "Internal Server Error",
+                    "callback_id": None,
+                    "result": None,
+                },
+                getattr(self, "parano_key", None),
+            )
+            for queue in self.sse_queues:
+                queue.put_nowait(err_payload)
+            dead_ws = []
+            for client in list(self.websockets):
+                try:
+                    await client.send_text(err_payload)
+                except Exception:
+                    dead_ws.append(client)
+            for client in dead_ws:
+                self.websockets.discard(client)
+
     async def broadcast_updates(
         self, result: Any = None, callback_id: str | None = None, ws: WebSocket | None = None
     ) -> None:

{htag-2.0.7 → htag-2.0.9}/htag.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htag
-Version: 2.0.7
+Version: 2.0.9
 Summary: Python3 GUI toolkit for building 'beautiful' applications for mobile, web, and desktop from a single codebase
 Author: manatlan
 License: MIT
@@ -101,6 +101,7 @@ htag is a Python library for building web applications using HTML, CSS, and Java
 *   **HTTP Fallback (SSE + POST)**: If WebSockets are blocked (e.g. strict proxies) or fail to connect, the client seamlessly falls back to HTTP POST for events and Server-Sent Events (SSE) for receiving UI updates.
 *   **Production Debug Mode**: Easily disable error reporting in the client by setting `debug=False` on the runner (e.g. `WebApp(App, debug=False).app`), preventing internal stacktraces from leaking to users.
 *   **Parano Mode (Payload Obfuscation)**: By initializing `WebApp(App, parano=True)`, all data exchanged between the frontend and backend is automatically obfuscated using a dynamic XOR cipher and Base64 wrapping, making network traffic unreadable to MITM proxies.
+*   **Progressive UI in Lifecycle Hooks**: Both `on_mount()` and `on_unmount()` fully support yielding intermediate UI states natively. `htag` intelligently queues `on_mount` generators until the client establishes a connection, and gracefully processes `on_unmount` broadcasts.
 *   **`.root`, `.parent`, and `.childs` properties**: Every `GTag` exposes its position in the component tree. `.root` references the main `Tag` instance, `.parent` references the direct parent component, and `.childs` is a list of its children. This allows components to easily navigate the DOM tree and trigger app-level actions.
 *   **Declarative UI with Context Managers (`with`)**: You can now build component trees visually using `with` blocks (e.g., `with Tag.div(): Tag.h1("Hello")`), removing the need for `self <= ...` boilerplate.
 *   **Modern Attribute Access (Dictionary Style)**: In addition to `Tag.div(_class="foo")` in constructors, you must now use `self["class"] = "foo"` for dynamic property management after instantiation. This is the only way to handle all attributes, including those with dashes (e.g., `self["data-id"] = 123`).

{htag-2.0.7 → htag-2.0.9}/htag.egg-info/SOURCES.txt

@@ -29,6 +29,8 @@ tests/test_fallback.py
 tests/test_interacting_robustness.py
 tests/test_lifecycle.py
 tests/test_memory.py
+tests/test_on_mount_yield.py
+tests/test_on_unmount_yield.py
 tests/test_parano.py
 tests/test_reactivity_edge_cases.py
 tests/test_runner_pyscript.py

{htag-2.0.7 → htag-2.0.9}/pyproject.toml

@@ -9,7 +9,7 @@ include-package-data = true
 
 [project]
 name = "htag"
-version = "2.0.7"
+version = "2.0.9"
 description = "Python3 GUI toolkit for building 'beautiful' applications for mobile, web, and desktop from a single codebase"
 readme = "README.md"
 requires-python = ">=3.10"

htag-2.0.9/tests/test_on_mount_yield.py

@@ -0,0 +1,90 @@
+import pytest
+import asyncio
+from typing import AsyncGenerator, Iterator
+
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+from htag import App, Tag
+from htag.web import WebApp
+
+class AppWithYields(App):
+    def init(self):
+        self += Tag.div("init", _id="status")
+        
+    def on_mount(self) -> Iterator[str]:
+        self.clear()
+        self += Tag.div("loading...", _id="status")
+        yield "update1"
+        self.clear()
+        self += Tag.div("done", _id="status")
+        yield "update2"
+
+@pytest.mark.asyncio
+async def test_on_mount_yields_websocket():
+    web = WebApp(AppWithYields)
+    
+    with TestClient(web.app) as client:
+        # 1. Initial page load (no websocket yet, on_mount generator should be queued)
+        response = client.get("/")
+        assert response.status_code == 200
+        assert "status" in response.text
+        assert "init" in response.text # initial state before yields are consumed
+        
+        # 2. Connect websocket
+        with client.websocket_connect("/ws") as websocket:
+            # First message received is the initial broadcast
+            data = websocket.receive_text()
+            assert "update" in data or "init" in data
+            
+            # The pending generators are consumed, wait for the broadcast updates
+            # update1 (loading...)
+            data = websocket.receive_text()
+            assert "loading..." in data
+            
+            # update2 (done)
+            data = websocket.receive_text()
+            assert "done" in data
+
+@pytest.mark.asyncio
+async def test_on_mount_yields_sse():
+    web = WebApp(AppWithYields)
+    
+    with TestClient(web.app) as client:
+        # 1. Initial page load
+        response = client.get("/")
+        assert response.status_code == 200
+        sid = response.cookies.get("htag_sid")
+        
+        # 2. Extract app instance
+        instance = web.instances[sid]
+        
+        # 3. Simulate _handle_sse
+        from starlette.requests import Request
+        
+        class MockRequest:
+            cookies = {"htag_sid": sid}
+            async def is_disconnected(self):
+                return False
+                
+        req = MockRequest()
+        
+        gen = instance._handle_sse(req)
+        
+        # Pull the first 'initial' payload + triggers background flush
+        initial_chunk = await gen.__anext__()
+        assert "data:" in initial_chunk
+        assert "loading..." not in initial_chunk # Pending update not yet given
+        
+        # To let the created task flush the items to the queue, yield control
+        await asyncio.sleep(0.01)
+        
+        # Pull first queued yield
+        q1 = await gen.__anext__()
+        assert "loading..." in q1
+        
+        # Pull second queued yield
+        q2 = await gen.__anext__()
+        assert "done" in q2
+        
+        # Cleanup tasks
+        instance.sse_queues.clear()

htag-2.0.9/tests/test_on_unmount_yield.py

@@ -0,0 +1,84 @@
+import pytest
+from typing import Iterator
+from starlette.testclient import TestClient
+from htag import App, Tag
+from htag.web import WebApp
+
+class UnmountingComponent(Tag.div):
+    def on_mount(self):
+        self.app_root = self.root
+
+    def on_unmount(self) -> Iterator[str]:
+        # Generators evaluate lazily, so we use the stored app_root
+        self.app_root.unmounted_triggered += 1
+        self.app_root.status.clear(str(self.app_root.unmounted_triggered))
+        yield "update1"
+        self.app_root.unmounted_triggered += 1
+        self.app_root.status.clear(str(self.app_root.unmounted_triggered))
+        yield "update2"
+
+class AppWithUnmount(App):
+    def init(self):
+        self.unmounted_triggered = 0
+        self.comp = UnmountingComponent("I will go away")
+        self += self.comp
+        
+        self.btn = Tag.button("Remove It", _onclick=self.do_remove, _id="btn")
+        self += self.btn
+        
+        # UI element to track state
+        self.status = Tag.div(self.unmounted_triggered, _id="status")
+        self += self.status
+
+    def do_remove(self, o):
+        self.comp.remove()
+        
+    def render_initial(self):
+        # ensure status is up-to-date
+        self.status.clear(str(self.unmounted_triggered))
+        return super().render_initial()
+
+@pytest.mark.asyncio
+async def test_on_unmount_yields_websocket():
+    web = WebApp(AppWithUnmount)
+    
+    with TestClient(web.app) as client:
+        # 1. Initial page load
+        response = client.get("/")
+        assert response.status_code == 200
+        
+        # 2. Connect websocket
+        with client.websocket_connect("/ws") as websocket:
+            # First message received is the initial broadcast
+            data = websocket.receive_text()
+            assert "I will go away" in data
+            
+            # 3. Simulate clicking the "Remove It" button
+            # We construct a fake message mimicking the browser sending the event
+            msg = {
+                "id": "btn",
+                "event": "click",
+                "data": {"callback_id": "cb1"}
+            }
+            # We have to obfuscate if parano_key is used, but by default it isn't
+            websocket.send_json(msg)
+            
+            # The click event will call do_remove()
+            # Which calls self.comp.remove() -> _trigger_unmount()
+            # The unmount yields twice, and we expect 3 payloads total or 2
+            # because the event handler completes, so the runner will send the first broadcast
+            # THEN it flushes pending generators
+            
+            # payload 1: Component removed (HTML delta), callback_id='cb1'
+            data = websocket.receive_text()
+            assert "cb1" in data # event resolution
+            
+            # payload 2: First yield in on_unmount
+            data = websocket.receive_text()
+            assert "update" in data # action: update
+            assert "1" in data # from the counter 1
+            
+            # payload 3: Second yield in on_unmount
+            data = websocket.receive_text()
+            assert "update" in data
+            assert "2" in data # from counter 2