pyjs-examples 0.0.1__tar.gz → 0.0.2__tar.gz

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyjs-examples
-Version: 0.0.1
+Version: 0.0.2
 Summary: Official example applications for PyJS.
 Author-email: Lex Berezhny <lex@damoti.com>
 License-Expression: BSD-3-Clause
@@ -18,7 +18,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
-Requires-Dist: pyjs==0.0.1
+Requires-Dist: pyjs==0.0.2
 Provides-Extra: test
 Requires-Dist: pytest>=9.0; extra == "test"
 
@@ -31,7 +31,7 @@ browse in the repository while installing as an ordinary top-level package.
 From the repository root, install the core and examples from a source checkout:
 
 ```bash
-python -m pip install -e . -e ./examples
+uv sync
 ```
 
 An installed PyJS release provides the same package through the `examples` extra:
@@ -40,13 +40,14 @@ An installed PyJS release provides the same package through the `examples` extra
 python -m pip install "pyjs[examples]"
 ```
 
-Run any complete application as a module:
+Run each complete application with the command shown:
 
 | Example | Command |
 | --- | --- |
 | [Calculator](calculator/) | `python -m pyjs_examples.calculator` |
 | [Chatroom](chatroom/) | `python -m pyjs_examples.chatroom` |
 | [Kanban board](kanban/) | `python -m pyjs_examples.kanban` |
+| [Navigation workspace](navigation/) | `python -m pyjs_examples.navigation` |
 | [NativeScript Counter](nativescript_counter/) | `python -m pyjs_examples.nativescript_counter` |
 | [Space Invaders](space_invaders/) | `python -m pyjs_examples.space_invaders` |
 | [TodoMVC](todomvc/) | `python -m pyjs_examples.todomvc` |

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/README.md

@@ -7,7 +7,7 @@ browse in the repository while installing as an ordinary top-level package.
 From the repository root, install the core and examples from a source checkout:
 
 ```bash
-python -m pip install -e . -e ./examples
+uv sync
 ```
 
 An installed PyJS release provides the same package through the `examples` extra:
@@ -16,13 +16,14 @@ An installed PyJS release provides the same package through the `examples` extra
 python -m pip install "pyjs[examples]"
 ```
 
-Run any complete application as a module:
+Run each complete application with the command shown:
 
 | Example | Command |
 | --- | --- |
 | [Calculator](calculator/) | `python -m pyjs_examples.calculator` |
 | [Chatroom](chatroom/) | `python -m pyjs_examples.chatroom` |
 | [Kanban board](kanban/) | `python -m pyjs_examples.kanban` |
+| [Navigation workspace](navigation/) | `python -m pyjs_examples.navigation` |
 | [NativeScript Counter](nativescript_counter/) | `python -m pyjs_examples.nativescript_counter` |
 | [Space Invaders](space_invaders/) | `python -m pyjs_examples.space_invaders` |
 | [TodoMVC](todomvc/) | `python -m pyjs_examples.todomvc` |

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/calculator/README.md

@@ -13,6 +13,7 @@ It demonstrates:
 - sign, percent, clear, and divide-by-zero behavior
 - asynchronous result persistence through an HTTP POST route
 - per-browser in-memory sessions that restore the last result after refresh
+- a Python-authored service worker with cache-first offline application loading
 - browser tests that interact with the real DOM through button events
 
 The example intentionally stays focused on calculator behavior. Reusable widget
@@ -30,7 +31,9 @@ From the repository root:
 Open `http://127.0.0.1:8000/`. Completing a calculation with `=` saves its
 result to the server. Refreshing the page restores that result through the
 browser's session cookie. Sessions are intentionally in memory, so restarting
-the server clears them.
+the server clears them. The app also registers `/calculator-serviceworker.js`.
+After its first controlled reload, the calculator can load and calculate while
+the browser is offline.
 
 ## Run the tests
 

pyjs_examples-0.0.2/calculator/__main__.py

@@ -0,0 +1,15 @@
+import os
+
+from pyjs.server import serve
+
+from .calculator import render, save_result, service_worker_javascript
+
+serve(
+    "pyjs_examples.calculator.calculator",
+    render=render,
+    routes={
+        ("POST", "/api/calculator/result"): save_result,
+        ("GET", "/calculator-serviceworker.js"): service_worker_javascript,
+    },
+    port=int(os.environ.get("PYJS_PORT", "8000")),
+)

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/calculator/calculator.py

@@ -1,10 +1,94 @@
 from pyjs import effect, js, nojs, state
 from pyjs.web.domx import ProxyElement, button, ref, tag, tw
 from pyjs.web.events import Event
-from pyjs.web.network import fetch
+from pyjs.web.network import Request, Response, fetch
+from pyjs.web.serviceworker import (
+    ExtendableEvent,
+    FetchEvent,
+    caches,
+    navigator,
+    service_worker_scope,
+)
 from pyjs.web.ui import Widget
 
 
+@js
+async def install_app_shell(cache_name: str, assets: list[str]):
+    cache = await caches.open(cache_name)
+    await cache.addAll(assets)
+    await service_worker_scope().skipWaiting()
+
+
+@js
+async def activate_app_shell():
+    await service_worker_scope().clients.claim()
+
+
+@js
+async def cache_first(request: Request, cache_name: str) -> Response:
+    cached = await caches.match(request)
+    if cached is not None:
+        return cached
+    response = await fetch(request.url)
+    cache = await caches.open(cache_name)
+    await cache.put(request, response.clone())
+    return response
+
+
+@js
+class InstallHandler:
+    def __init__(self, cache_name: str, assets: list[str]):
+        self.cache_name = cache_name
+        self.assets = assets
+
+    @js(include=True)
+    def handleEvent(self, event: ExtendableEvent):
+        event.waitUntil(install_app_shell(self.cache_name, self.assets))
+
+
+@js
+class ActivateHandler:
+    @js(include=True)
+    def handleEvent(self, event: ExtendableEvent):
+        event.waitUntil(activate_app_shell())
+
+
+@js
+class FetchHandler:
+    def __init__(self, cache_name: str):
+        self.cache_name = cache_name
+
+    @js(include=True)
+    def handleEvent(self, event: FetchEvent):
+        if event.request.method == "GET":
+            event.respondWith(cache_first(event.request, self.cache_name))
+
+
+@js
+def service_worker_main():
+    cache_name = "pyjs-calculator-v1"
+    scope = service_worker_scope()
+    scope.addEventListener("install", InstallHandler(cache_name, ["/", "/index.css"]))
+    scope.addEventListener("activate", ActivateHandler())
+    scope.addEventListener("fetch", FetchHandler(cache_name))
+
+
+@nojs
+def service_worker_javascript(request):
+    from pyjs.server import ServerResponse
+    from pyjs.transpiler import bundle
+
+    source, _ = bundle(service_worker_main, include_main=True, include_css=False)
+    return ServerResponse(
+        source,
+        content_type="application/javascript",
+        headers={
+            "Cache-Control": "no-cache",
+            "Service-Worker-Allowed": "/",
+        },
+    )
+
+
 @js
 class CalculatorKeyListener:
     def __init__(self, app: CalculatorApp, kind: str, value: str):
@@ -78,8 +162,14 @@ class CalculatorApp(Widget):
     replace_display = state(True)
     error = state(False)
     save_url = state("")
-
-    def __init__(self, initial_value: str = "0", save_url: str = ""):
+    service_worker_url = state("")
+
+    def __init__(
+        self,
+        initial_value: str = "0",
+        save_url: str = "",
+        service_worker_url: str = "",
+    ):
         super().__init__()
         self.display = ref(
             tag(
@@ -98,6 +188,7 @@ class CalculatorApp(Widget):
         )
         self.display_value = initial_value
         self.save_url = save_url
+        self.service_worker_url = service_worker_url
 
         self.clear_button = ref(CalculatorKey("AC", "clear", "action", False))
         self.clear_button.bind(self, "action", "clear")
@@ -180,6 +271,12 @@ class CalculatorApp(Widget):
             card,
         )
 
+    async def initialize(self):
+        if self.service_worker_url == "":
+            return
+        registration = await navigator.serviceWorker.register(self.service_worker_url)
+        self.set_data("service-worker", registration.scope)
+
     @effect(display_value)
     def render_display(self):
         self.display.textContent = self.display_value
@@ -294,13 +391,25 @@ class CalculatorApp(Widget):
             self.percent()
 
 
-def main(initial_value: str = "0", save_url: str = ""):
-    return CalculatorApp(initial_value=initial_value, save_url=save_url)
+def main(
+    initial_value: str = "0",
+    save_url: str = "",
+    service_worker_url: str = "",
+):
+    return CalculatorApp(
+        initial_value=initial_value,
+        save_url=save_url,
+        service_worker_url=service_worker_url,
+    )
 
 
 @nojs
 def render(request):
-    return main(request.session.get("last_result", "0"), "/api/calculator/result")
+    return main(
+        request.session.get("last_result", "0"),
+        "/api/calculator/result",
+        "/calculator-serviceworker.js",
+    )
 
 
 @nojs
@@ -316,10 +425,16 @@ def save_result(request):
 
 
 if __name__ == "__main__":
+    import os
+
     from pyjs.server import serve
 
     serve(
         "calculator",
         render=render,
-        routes={("POST", "/api/calculator/result"): save_result},
+        routes={
+            ("POST", "/api/calculator/result"): save_result,
+            ("GET", "/calculator-serviceworker.js"): service_worker_javascript,
+        },
+        port=int(os.environ.get("PYJS_PORT", "8000")),
     )

pyjs_examples-0.0.2/calculator/tests/test_pwa.py

@@ -0,0 +1,67 @@
+import asyncio
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from pyjs.tooling import stop_process
+from pyjs.tooling.browser import Browser, free_port, wait_for_http
+
+pytestmark = pytest.mark.pyjs_python
+
+
+def test_calculator_registers_python_service_worker_and_runs_offline():
+    async def run():
+        port = free_port()
+        url = f"http://127.0.0.1:{port}/"
+        environment = os.environ.copy()
+        environment["PYJS_PORT"] = str(port)
+        environment["PYTHONUNBUFFERED"] = "1"
+        application = Path(__file__).parents[1] / "calculator.py"
+        server = subprocess.Popen(
+            [sys.executable, str(application)],
+            env=environment,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        try:
+            try:
+                await wait_for_http(url, timeout=120)
+            except TimeoutError as error:
+                stop_process(server)
+                output = server.stdout.read() if server.stdout is not None else ""
+                raise TimeoutError(f"{error}\nServer output:\n{output}") from error
+            async with Browser() as browser:
+                page = await browser.new_page(url)
+                await page.wait_for_selector("calculator-app")
+                await page.wait_for(
+                    "navigator.serviceWorker.controller !== null",
+                    "the calculator service worker to control the page",
+                )
+
+                scope = await page.attribute("calculator-app", "data-service-worker")
+                assert scope == url
+
+                await page.navigate(url)
+                await page.wait_for_selector('[data-testid="calculator-display"]')
+                cached_urls = await page.evaluate(
+                    "(async () => {"
+                    " const cache = await caches.open('pyjs-calculator-v1');"
+                    " return (await cache.keys()).map((request) => request.url);"
+                    "})()"
+                )
+                assert url in cached_urls
+                assert any(cached_url.endswith(".js") for cached_url in cached_urls)
+
+                await page.set_offline()
+                await page.navigate(url)
+                await page.wait_for_selector('[data-testid="calculator-display"]')
+                await page.click('[data-key="7"]')
+                assert await page.text('[data-testid="calculator-display"]') == "7"
+                assert page.exceptions == []
+        finally:
+            stop_process(server)
+
+    asyncio.run(run())

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/chatroom/chatroom.py

@@ -1,31 +1,29 @@
+from typing import TypedDict
+
 from pyjs import effect, js, nojs, state
+from pyjs.javascript import JSON
 from pyjs.web.dom import location, sessionStorage
 from pyjs.web.domx import button, form, input, ref, tag, tw
 from pyjs.web.events import Event, MessageEvent
-from pyjs.web.javascript import JSON
 from pyjs.web.network import WebSocket
 from pyjs.web.ui import Widget
 
 
-@js
-class ChatMessage:
-    def __init__(self):
-        self.id = 0
-        self.room = ""
-        self.sender = ""
-        self.text = ""
-        self.time = ""
+class ChatMessage(TypedDict):
+    id: int
+    room: str
+    sender: str
+    text: str
+    time: str
 
 
-@js
-class ChatSnapshot:
-    def __init__(self):
-        self.type = ""
-        self.room = ""
-        self.rooms: list[str] = []
-        self.messages: list[ChatMessage] = []
-        self.users: list[str] = []
-        self.message = ""
+class ChatSnapshot(TypedDict):
+    type: str
+    room: str
+    rooms: list[str]
+    messages: list[ChatMessage]
+    users: list[str]
+    message: str
 
 
 @js
@@ -441,10 +439,7 @@ class ChatRoomApp(Widget):
     def initialize(self):
         self.socket: WebSocket | None = None
         name = sessionStorage.getItem("pyjs-chatroom-display-name")
-        if name is None:
-            self.show_sign_in()
-            return
-        if name == "":
+        if name is None or name == "":
             self.show_sign_in()
             return
         self.name = name
@@ -535,14 +530,14 @@ class ChatRoomApp(Widget):
                 socket.send(JSON.stringify(message))
 
     def receive(self, message: ChatSnapshot):
-        if message.type == "error":
-            self.show_error(message.message)
+        if message["type"] == "error":
+            self.show_error(message["message"])
             return
         self.hide_error()
-        self.room = message.room
-        self.render_rooms(message.rooms)
-        self.render_messages(message.messages)
-        self.render_members(message.users)
+        self.room = message["room"]
+        self.render_rooms(message["rooms"])
+        self.render_messages(message["messages"])
+        self.render_members(message["users"])
 
     def render_rooms(self, rooms: list[str]):
         self.room_list.replaceChildren()
@@ -604,7 +599,7 @@ class ChatRoomApp(Widget):
                 tag(
                     "article",
                     tw("group flex gap-3 rounded-lg px-2 py-2 hover:bg-slate-50"),
-                    {"data-message-id": str(message.id)},
+                    {"data-message-id": str(message["id"])},
                     tag(
                         "div",
                         tw(
@@ -619,8 +614,16 @@ class ChatRoomApp(Widget):
                         tag(
                             "div",
                             tw("flex items-baseline gap-2"),
-                            tag("strong", tw("text-sm font-bold text-slate-900"), message.sender),
-                            tag("time", tw("text-[0.7rem] text-slate-400"), message.time),
+                            tag(
+                                "strong",
+                                tw("text-sm font-bold text-slate-900"),
+                                message["sender"],
+                            ),
+                            tag(
+                                "time",
+                                tw("text-[0.7rem] text-slate-400"),
+                                message["time"],
+                            ),
                         ),
                         tag(
                             "p",
@@ -628,7 +631,7 @@ class ChatRoomApp(Widget):
                                 "mt-0.5 whitespace-pre-wrap break-words text-sm leading-6 "
                                 "text-slate-700"
                             ),
-                            message.text,
+                            message["text"],
                         ),
                     ),
                 )

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/chatroom/tests/test_browser_chatroom.py

@@ -1,7 +1,8 @@
 import pytest
 from pyjs import js
-from pyjs.testing.web import mount, require_element
+from pyjs.testing.web import mount
 from pyjs.web.dom import sessionStorage
+from pyjs.web.domx import require_element
 from pyjs.web.events import Event
 from pyjs_examples.chatroom.chatroom import ChatMessage, ChatRoomApp, ChatSnapshot
 
@@ -36,18 +37,21 @@ def test_chatroom_prompts_for_a_per_tab_display_name():
 def test_chatroom_renders_rooms_messages_and_presence_from_a_snapshot():
     sessionStorage.setItem("pyjs-chatroom-display-name", "Alice")
     app = mounted_chatroom()
-    message = ChatMessage()
-    message.id = 1
-    message.room = "design"
-    message.sender = "Bob"
-    message.text = "The new navigation is ready."
-    message.time = "09:42"
-    snapshot = ChatSnapshot()
-    snapshot.type = "snapshot"
-    snapshot.room = "design"
-    snapshot.rooms = ["general", "design"]
-    snapshot.messages = [message]
-    snapshot.users = ["Alice", "Bob"]
+    message = ChatMessage(
+        id=1,
+        room="design",
+        sender="Bob",
+        text="The new navigation is ready.",
+        time="09:42",
+    )
+    snapshot = ChatSnapshot(
+        type="snapshot",
+        room="design",
+        rooms=["general", "design"],
+        messages=[message],
+        users=["Alice", "Bob"],
+        message="",
+    )
 
     app.receive(snapshot)
 

{pyjs_examples-0.0.1 → pyjs_examples-0.0.2}/kanban/tests/test_browser_kanban.py

@@ -147,4 +147,9 @@ def test_kanban_visual_showcase():
 
     assert card_order(board.in_progress) == "drag-drop,empty-states,onboarding-audit"
     mount(board.columns)
-    assert_render(board.columns, "kanban-board", pixel_threshold=10)
+    assert_render(
+        board.columns,
+        "kanban-board",
+        pixel_threshold=10,
+        max_different_pixel_ratio=0.06,
+    )

pyjs_examples-0.0.2/navigation/README.md

@@ -0,0 +1,20 @@
+# Navigation Workspace Example
+
+This example demonstrates server-rendered pages inside a persistent application layout. Normal
+requests return complete HTML documents. Navigation initiated inside the application requests only
+the selected page, updates the `PageOutlet`, and preserves the sidebar and header without requiring
+a client-side routing table.
+
+Run it from the repository root:
+
+```bash
+.venv/bin/python -m pyjs_examples.navigation
+```
+
+Open `http://127.0.0.1:8000/`, then move between the eight pages using the sidebar.
+
+Run its server and browser coverage with:
+
+```bash
+.venv/bin/python -m pytest -q examples/navigation/tests
+```

pyjs_examples-0.0.2/navigation/__init__.py

@@ -0,0 +1 @@
+"""Persistent layout and partial page navigation example."""

pyjs_examples-0.0.2/navigation/__main__.py

@@ -0,0 +1,49 @@
+import os
+
+from pyjs.server import serve
+from pyjs_examples.navigation.navigation import (
+    analytics_page,
+    analytics_view,
+    calendar_page,
+    calendar_view,
+    layout,
+    messages_page,
+    messages_view,
+    overview_page,
+    overview_view,
+    projects_page,
+    projects_view,
+    reports_page,
+    reports_view,
+    settings_page,
+    settings_view,
+    team_page,
+    team_view,
+)
+
+serve(
+    "pyjs_examples.navigation.navigation",
+    routes={
+        ("GET", "/"): overview_page,
+        ("GET", "/analytics"): analytics_page,
+        ("GET", "/calendar"): calendar_page,
+        ("GET", "/messages"): messages_page,
+        ("GET", "/projects"): projects_page,
+        ("GET", "/reports"): reports_page,
+        ("GET", "/settings"): settings_page,
+        ("GET", "/team"): team_page,
+    },
+    layout=layout,
+    layout_id="atlas",
+    page_entry_points=(
+        overview_view,
+        analytics_view,
+        calendar_view,
+        messages_view,
+        projects_view,
+        reports_view,
+        settings_view,
+        team_view,
+    ),
+    port=int(os.environ.get("PYJS_PORT", "8000")),
+)