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

pyjs_examples-0.4.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Lex Berezhny
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyjs_examples-0.4.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pyjs-examples
+Version: 0.4.0
+Summary: Official example applications for PyJS.
+Author-email: Lex Berezhny <lex@damoti.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/pyjs/pyjs
+Project-URL: Source, https://github.com/pyjs/pyjs
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjs==0.4.0
+Provides-Extra: store
+Requires-Dist: django<6.2,>=6.0; extra == "store"
+Requires-Dist: pydantic<3,>=2; extra == "store"
+Requires-Dist: pyjs-extras==0.4.0; extra == "store"
+Requires-Dist: uvicorn<1,>=0.52; extra == "store"
+Provides-Extra: test
+Requires-Dist: django<6.2,>=6.0; extra == "test"
+Requires-Dist: pydantic<3,>=2; extra == "test"
+Requires-Dist: pyjs-extras==0.4.0; extra == "test"
+Requires-Dist: pytest>=9.0; extra == "test"
+Requires-Dist: uvicorn<1,>=0.52; extra == "test"
+Dynamic: license-file
+
+# PyJS Examples
+
+This directory is the source tree for the separately installable
+`pyjs-examples` distribution. Setuptools maps it to the `pyjs_examples` import
+package while keeping each application easy to browse in the repository.
+
+Install the core and examples from a source checkout:
+
+```bash
+uv sync
+```
+
+An installed release provides the examples through an extra:
+
+```bash
+python -m pip install "pyjs[examples]"
+```
+
+## Application responsibilities
+
+The examples progress from small programs to composed, full-stack systems.
+Features may overlap when that makes an application more realistic.
+
+| Example | Role | Principal PyJS coverage |
+| --- | --- | --- |
+| [Counter](counter.py) | Smallest app | DOM, events, one-file tests |
+| [Calculator](calculator/) | Universal app | Web, PWA, Android, SSR, state |
+| [Components](components/) | UI reference | Widgets, forms, navigation |
+| [Notes](notes/) | Personal app | Web, Android, drag/drop, restore |
+| [Chat](chat/) | Real-time starter | WebSockets, multi-window, plans |
+| [Store](store/) | Business app | Django, JSON:API, SSE, themes, cursor feeds |
+| [Space Invaders](space_invaders/) | GPU game | WebGPU, input, render tests |
+
+Run an application with its module name, for example:
+
+```bash
+python -m pyjs_examples.calculator
+python -m pyjs_examples.components
+python -m pyjs_examples.notes
+python -m pyjs_examples.chat
+python -m pyjs_examples.store
+```
+
+Install `pyjs-examples[store]` before running Store from a release package.
+
+Calculator and Notes accept `--android` to build and launch their NativeScript
+versions. Their default command serves the web version.
+
+Components is also the source and test surface for the planned website
+component reference. It combines the former catalog, workspace, navigation,
+and focused dialog sample in one application.
+
+Notes combines the former Kanban board with the mobile notes application. It
+uses DOM-owned ordering, drag/drop, server restoration, and visual tests.
+
+Store is the canonical Django and typed client/server example. It also owns the
+themability story, signed cursor feeds, infinite scrolling, and data-driven
+charts.
+
+## Templates
+
+List, inspect, or copy examples using the core scaffolding command:
+
+```bash
+pyjs template
+pyjs template pyjs_examples.calculator
+pyjs create my-calculator --template pyjs_examples.calculator
+pyjs create --single-file my_counter.py --template pyjs_examples.counter
+```
+
+The distribution registers modules and packages through the `pyjs.templates`
+entry-point group. PyJS infers file and directory templates from normal Python
+module structure instead of hardcoding a catalog.

pyjs_examples-0.4.0/README.md

@@ -0,0 +1,73 @@
+# PyJS Examples
+
+This directory is the source tree for the separately installable
+`pyjs-examples` distribution. Setuptools maps it to the `pyjs_examples` import
+package while keeping each application easy to browse in the repository.
+
+Install the core and examples from a source checkout:
+
+```bash
+uv sync
+```
+
+An installed release provides the examples through an extra:
+
+```bash
+python -m pip install "pyjs[examples]"
+```
+
+## Application responsibilities
+
+The examples progress from small programs to composed, full-stack systems.
+Features may overlap when that makes an application more realistic.
+
+| Example | Role | Principal PyJS coverage |
+| --- | --- | --- |
+| [Counter](counter.py) | Smallest app | DOM, events, one-file tests |
+| [Calculator](calculator/) | Universal app | Web, PWA, Android, SSR, state |
+| [Components](components/) | UI reference | Widgets, forms, navigation |
+| [Notes](notes/) | Personal app | Web, Android, drag/drop, restore |
+| [Chat](chat/) | Real-time starter | WebSockets, multi-window, plans |
+| [Store](store/) | Business app | Django, JSON:API, SSE, themes, cursor feeds |
+| [Space Invaders](space_invaders/) | GPU game | WebGPU, input, render tests |
+
+Run an application with its module name, for example:
+
+```bash
+python -m pyjs_examples.calculator
+python -m pyjs_examples.components
+python -m pyjs_examples.notes
+python -m pyjs_examples.chat
+python -m pyjs_examples.store
+```
+
+Install `pyjs-examples[store]` before running Store from a release package.
+
+Calculator and Notes accept `--android` to build and launch their NativeScript
+versions. Their default command serves the web version.
+
+Components is also the source and test surface for the planned website
+component reference. It combines the former catalog, workspace, navigation,
+and focused dialog sample in one application.
+
+Notes combines the former Kanban board with the mobile notes application. It
+uses DOM-owned ordering, drag/drop, server restoration, and visual tests.
+
+Store is the canonical Django and typed client/server example. It also owns the
+themability story, signed cursor feeds, infinite scrolling, and data-driven
+charts.
+
+## Templates
+
+List, inspect, or copy examples using the core scaffolding command:
+
+```bash
+pyjs template
+pyjs template pyjs_examples.calculator
+pyjs create my-calculator --template pyjs_examples.calculator
+pyjs create --single-file my_counter.py --template pyjs_examples.counter
+```
+
+The distribution registers modules and packages through the `pyjs.templates`
+entry-point group. PyJS infers file and directory templates from normal Python
+module structure instead of hardcoding a catalog.

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

@@ -6,7 +6,8 @@ example for pyjs browser-target testing.
 It demonstrates:
 
 - calculator state and behavior owned by a custom element
-- typed `state()` fields serialized to DOM attributes and rendered with `@effect`
+- typed `state()` fields serialized to DOM attributes and rendered with
+  `@effect`
 - a centered responsive custom-element UI
 - digit and decimal entry
 - addition, subtraction, multiplication, and division
@@ -14,6 +15,7 @@ It demonstrates:
 - 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
+- a native Android implementation using the same arithmetic primitive
 - browser tests that interact with the real DOM through button events
 
 The example intentionally stays focused on calculator behavior. Reusable widget
@@ -25,7 +27,7 @@ coverage, including the dropdown menu and floating positioning, lives under
 From the repository root:
 
 ```bash
-.venv/bin/python -m pyjs_examples.calculator
+python -m pyjs_examples.calculator
 ```
 
 Open `http://127.0.0.1:8000/`. Completing a calculation with `=` saves its
@@ -35,24 +37,38 @@ 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 native Android version on an existing emulator, or let the managed
+NativeScript tooling start its configured device:
+
+```console
+python -m pyjs_examples.calculator --android
+```
+
 ## Run the tests
 
 From the repository root, run the Python target:
 
 ```bash
-.venv/bin/python -m pytest -q examples/calculator/tests
+pytest -q examples/calculator/tests
 ```
 
 Run the same model tests plus the browser-only UI tests in the browser:
 
 ```bash
-.venv/bin/python -m pytest -q examples/calculator/tests --pyjs-target=web
+pytest -q examples/calculator/tests --pyjs-target=web
 ```
 
 The pytest plugin starts or reconnects to the browser-test daemon on
 `127.0.0.1:8765`. To keep the daemon alive while iterating:
 
 ```bash
-.venv/bin/python -m pytest -q examples/calculator/tests --pyjs-target=web \
+pytest -q examples/calculator/tests --pyjs-target=web \
   --pyjs-daemon-idle-seconds=0
 ```
+
+Run the Android interaction test with:
+
+```console
+pytest -q examples/calculator/tests/test_android_calculator.py \
+  --pyjs-target=android --pyjs-android-avd=Routine_Test
+```

pyjs_examples-0.4.0/calculator/__init__.py

@@ -0,0 +1 @@
+"""A tested universal calculator for the Web, PWA, and Android targets."""

pyjs_examples-0.4.0/calculator/__main__.py

@@ -0,0 +1,21 @@
+import os
+import sys
+
+from pyjs.server.dev import serve
+
+from .calculator import render, save_result, service_worker_javascript
+
+if "--android" in sys.argv:
+    from .android import run_android
+
+    run_android()
+else:
+    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.4.0/calculator/android.py

@@ -0,0 +1,225 @@
+from pyjs import js
+from pyjs.nativescript import (
+    Application,
+    Button,
+    EventData,
+    GridLayout,
+    Label,
+    Page,
+    StackLayout,
+)
+from pyjs.tooling.nativescript import NativeScriptProject
+
+from .calculator import calculate_result
+
+
+@js
+class CalculatorButtonListener:
+    def __init__(self, calculator: AndroidCalculator, kind: str, value: str):
+        self.calculator = calculator
+        self.kind = kind
+        self.value = value
+
+    def handleEvent(self, event: EventData):
+        self.calculator.press(self.kind, self.value)
+
+
+@js
+class AndroidCalculator:
+    def __init__(self):
+        self.display_value = "0"
+        self.stored_value = 0.0
+        self.pending_operator = ""
+        self.replace_display = True
+        self.error = False
+
+        self.display = Label()
+        self.display.id = "calculator-display"
+        self.display.testID = "calculator-display"
+        self.display.text = self.display_value
+        self.display.className = (
+            "mb-4 rounded-2xl bg-slate-950 p-5 text-right text-5xl "
+            "font-bold text-white"
+        )
+
+    def update_display(self):
+        self.display.text = self.display_value
+
+    def clear(self):
+        self.display_value = "0"
+        self.stored_value = 0.0
+        self.pending_operator = ""
+        self.replace_display = True
+        self.error = False
+        self.update_display()
+
+    def value(self) -> float:
+        if self.error:
+            return 0.0
+        return float(self.display_value)
+
+    def input_digit(self, digit: str):
+        if self.error:
+            self.clear()
+        if self.replace_display or self.display_value == "0":
+            self.display_value = digit
+            self.replace_display = False
+        else:
+            self.display_value += digit
+        self.update_display()
+
+    def input_decimal(self):
+        if self.error:
+            self.clear()
+        if self.replace_display:
+            self.display_value = "0."
+            self.replace_display = False
+        elif len(self.display_value.split(".")) == 1:
+            self.display_value += "."
+        self.update_display()
+
+    def choose_operator(self, operator: str):
+        if self.error:
+            return
+        if self.pending_operator != "" and not self.replace_display:
+            self.calculate()
+            if self.error:
+                return
+        self.stored_value = float(self.display_value)
+        self.pending_operator = operator
+        self.replace_display = True
+
+    def toggle_sign(self):
+        if self.error or self.display_value == "0" or self.display_value == "0.0":
+            return
+        self.display_value = str(0.0 - float(self.display_value))
+        self.update_display()
+
+    def percent(self):
+        if self.error:
+            return
+        self.display_value = str(float(self.display_value) / 100.0)
+        self.replace_display = True
+        self.update_display()
+
+    def calculate(self) -> float:
+        operator = self.pending_operator
+        if self.error or operator == "":
+            return self.value()
+        right = float(self.display_value)
+        if operator == "/" and right == 0.0:
+            self.display_value = "Error"
+            self.pending_operator = ""
+            self.replace_display = True
+            self.error = True
+            self.update_display()
+            return 0.0
+        result = calculate_result(self.stored_value, right, operator)
+        self.display_value = str(result)
+        self.stored_value = result
+        self.pending_operator = ""
+        self.replace_display = True
+        self.update_display()
+        return result
+
+    def press(self, kind: str, value: str):
+        if kind == "digit":
+            self.input_digit(value)
+        elif kind == "decimal":
+            self.input_decimal()
+        elif kind == "operator":
+            self.choose_operator(value)
+        elif kind == "equals":
+            self.calculate()
+        elif value == "clear":
+            self.clear()
+        elif value == "sign":
+            self.toggle_sign()
+        else:
+            self.percent()
+
+    def key(self, label: str, value: str, kind: str, row: int, column: int) -> Button:
+        key = Button()
+        key.id = "key-" + value
+        key.testID = "key-" + value
+        key.text = label
+        key.row = row
+        key.column = column
+        if kind == "operator" or kind == "equals":
+            key.className = (
+                "m-1 h-14 rounded-xl bg-amber-500 text-2xl font-bold text-white"
+            )
+        else:
+            key.className = (
+                "m-1 h-14 rounded-xl bg-slate-100 text-2xl font-semibold "
+                "text-slate-950"
+            )
+        listener = CalculatorButtonListener(self, kind, value)
+        key.on(Button.tapEvent, listener.handleEvent)
+        return key
+
+    def page(self) -> Page:
+        keypad = GridLayout()
+        keypad.rows = "auto,auto,auto,auto,auto"
+        keypad.columns = "*,*,*,*"
+        labels = [
+            ("AC", "clear", "clear"),
+            ("±", "sign", "action"),
+            ("%", "percent", "action"),
+            ("÷", "/", "operator"),
+            ("7", "7", "digit"),
+            ("8", "8", "digit"),
+            ("9", "9", "digit"),
+            ("×", "*", "operator"),
+            ("4", "4", "digit"),
+            ("5", "5", "digit"),
+            ("6", "6", "digit"),
+            ("−", "-", "operator"),
+            ("1", "1", "digit"),
+            ("2", "2", "digit"),
+            ("3", "3", "digit"),
+            ("+", "+", "operator"),
+            ("0", "0", "digit"),
+            (".", ".", "decimal"),
+            ("=", "=", "equals"),
+        ]
+        index = 0
+        for label, value, kind in labels:
+            keypad.addChild(self.key(label, value, kind, index // 4, index % 4))
+            index += 1
+
+        content = StackLayout()
+        content.className = "bg-slate-900 p-5"
+        content.verticalAlignment = "middle"
+        title = Label()
+        title.text = "PyJS Calculator"
+        title.className = "mb-4 text-center text-2xl font-bold text-sky-300"
+        content.addChild(title)
+        content.addChild(self.display)
+        content.addChild(keypad)
+
+        page = Page()
+        page.actionBarHidden = True
+        page.className = "bg-slate-900"
+        page.content = content
+        return page
+
+
+@js
+def create_android_page() -> Page:
+    return AndroidCalculator().page()
+
+
+@js
+def android_main():
+    Application.run(create_android_page)
+
+
+def run_android():
+    project = NativeScriptProject(
+        android_main,
+        name="PyJS Calculator",
+        app_id="org.pyjs.calculator",
+    )
+    device = project.run_android()
+    print(f"PyJS Calculator is running on {device.identifier}.")

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

@@ -12,6 +12,17 @@ from pyjs.web.serviceworker import (
 from pyjs.web.ui import Widget
 
 
+@js
+def calculate_result(left: float, right: float, operator: str) -> float:
+    if operator == "+":
+        return left + right
+    if operator == "-":
+        return left - right
+    if operator == "*":
+        return left * right
+    return left / right
+
+
 @js
 async def install_app_shell(cache_name: str, assets: list[str]):
     cache = await caches.open(cache_name)
@@ -41,14 +52,12 @@ class InstallHandler:
         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())
 
@@ -58,7 +67,6 @@ 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))
@@ -75,11 +83,11 @@ def service_worker_main():
 
 @nojs
 def service_worker_javascript(request):
-    from pyjs.server import ServerResponse
+    from pyjs.server.dev import Response
     from pyjs.transpiler import bundle
 
     source, _ = bundle(service_worker_main, include_main=True, include_css=False)
-    return ServerResponse(
+    return Response(
         source,
         content_type="application/javascript",
         headers={
@@ -96,7 +104,6 @@ class CalculatorKeyListener:
         self.kind = kind
         self.value = value
 
-    @js(include=True)
     async def handleEvent(self, event: Event):
         self.app.press(self.kind, self.value)
         if self.kind == "equals" and not self.app.error:
@@ -334,15 +341,6 @@ class CalculatorApp(Widget):
         self.pending_operator = operator
         self.replace_display = True
 
-    def calculate_result(self, left: float, right: float, operator: str) -> float:
-        if operator == "+":
-            return left + right
-        if operator == "-":
-            return left - right
-        if operator == "*":
-            return left * right
-        return left / right
-
     def calculate(self) -> float:
         operator = self.pending_operator
         if self.error or operator == "":
@@ -354,7 +352,7 @@ class CalculatorApp(Widget):
             self.replace_display = True
             self.error = True
             return 0.0
-        result = self.calculate_result(self.stored_value, right, operator)
+        result = calculate_result(self.stored_value, right, operator)
         self.display_value = str(result)
         self.stored_value = result
         self.pending_operator = ""
@@ -427,7 +425,7 @@ def save_result(request):
 if __name__ == "__main__":
     import os
 
-    from pyjs.server import serve
+    from pyjs.server.dev import serve
 
     serve(
         "calculator",

pyjs_examples-0.4.0/calculator/tests/test_android_calculator.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+import pytest
+from pyjs.testing.android import AndroidTestSession
+from pyjs.tooling.android import AndroidSDK
+from pyjs.tooling.nativescript import NativeScriptProject
+from pyjs_examples.calculator.android import android_main
+
+pytestmark = pytest.mark.pyjs_android
+
+
+def test_calculator_runs_on_android(request, pyjs_artifacts_dir: Path):
+    android = AndroidSDK()
+    project = NativeScriptProject(
+        android_main,
+        name="PyJS Calculator",
+        app_id="org.pyjs.calculator",
+        android=android,
+    )
+    device = project.run_android(request.config.getoption("--pyjs-android-avd"))
+    session = AndroidTestSession(android, device, project.app_id)
+    artifacts = pyjs_artifacts_dir / "android"
+
+    with session.artifacts_on_failure(artifacts, "calculator"):
+        session.launch()
+        session.wait_for_element(test_id="calculator-display", text="0")
+        session.tap_element(test_id="key-1")
+        session.tap_element(test_id="key-+")
+        session.tap_element(test_id="key-2")
+        session.tap_element(test_id="key-=")
+        session.wait_for_element(test_id="calculator-display", text="3.0")
+        assert session.log_errors() == ""
+
+    session.capture_artifacts(artifacts, "calculator")

pyjs_examples-0.4.0/calculator/tests/test_android_calculator_model.py

@@ -0,0 +1,26 @@
+import pytest
+from pyjs_examples.calculator.android import AndroidCalculator
+
+pytestmark = pytest.mark.pyjs_python
+
+
+def test_android_calculator_uses_the_same_arithmetic_behavior():
+    calculator = AndroidCalculator()
+
+    calculator.input_digit("1")
+    calculator.input_digit("2")
+    calculator.choose_operator("+")
+    calculator.input_digit("7")
+
+    assert calculator.calculate() == 19.0
+    assert calculator.display.text == "19.0"
+
+
+def test_android_calculator_builds_a_complete_native_keypad():
+    calculator = AndroidCalculator()
+    page = calculator.page()
+
+    assert page.content.getViewById("calculator-display") is calculator.display
+    assert page.content.getViewById("key-clear") is not None
+    assert page.content.getViewById("key-+") is not None
+    assert page.content.getViewById("key-=") is not None