Add @when decorator (#1428)

* Add new _event_handling.py file with @when decorator

* @when decorate is in pyscript package namespace/_all__

* Write tests in new test_event_handling.py

* Add docs for @when decorator

------------

Co-authored-by: Mariana Meireles <marian.meireles@gmail.com>

pyscriptjs/src/python/pyscript/__init__.py

@@ -1,5 +1,6 @@
 from _pyscript_js import showWarning
 
+from ._event_handling import when
 from ._event_loop import LOOP as loop
 from ._event_loop import run_until_complete
 from ._html import (
@@ -51,4 +52,5 @@ __all__ = [
     "__version__",
     "version_info",
     "showWarning",
+    "when",
 ]

pyscriptjs/src/python/pyscript/_event_handling.py

@@ -0,0 +1,29 @@
+import inspect
+
+import js
+from pyodide.ffi.wrappers import add_event_listener
+
+
+def when(event_type=None, selector=None):
+    """
+    Decorates a function and passes py-* events to the decorated function
+    The events might or not be an argument of the decorated function
+    """
+
+    def decorator(func):
+        elements = js.document.querySelectorAll(selector)
+        sig = inspect.signature(func)
+        # Function doesn't receive events
+        if not sig.parameters:
+
+            def wrapper(*args, **kwargs):
+                func()
+
+            for el in elements:
+                add_event_listener(el, event_type, wrapper)
+        else:
+            for el in elements:
+                add_event_listener(el, event_type, func)
+        return func
+
+    return decorator

pyscriptjs/tests/integration/test_01_basic.py

@@ -316,6 +316,7 @@ class TestBasic(PyScriptTest):
         )
         btn = self.page.wait_for_selector("button")
         btn.click()
+        self.wait_for_console("hello world!")
         assert self.console.log.lines[-1] == "hello world!"
         assert self.console.error.lines == []
 

pyscriptjs/tests/integration/test_event_handling.py

@@ -0,0 +1,194 @@
+from .support import PyScriptTest, skip_worker
+
+
+class TestEventHandler(PyScriptTest):
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_when_decorator_with_event(self):
+        """When the decorated function takes a single parameter,
+        it should be passed the event object
+        """
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                def foo(evt):
+                    print(f"I've clicked {evt.target} with id {evt.target.id}")
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").click()
+        console_text = self.console.all.lines
+        self.wait_for_console("I've clicked [object HTMLButtonElement] with id foo_id")
+        assert "I've clicked [object HTMLButtonElement] with id foo_id" in console_text
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_when_decorator_without_event(self):
+        """When the decorated function takes no parameters (not including 'self'),
+        it should be called without the event object
+        """
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                def foo():
+                    print("The button was clicked")
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").click()
+        self.wait_for_console("The button was clicked")
+        assert "The button was clicked" in self.console.log.lines
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_multiple_when_decorators_with_event(self):
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <button id="bar_id">bar_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                def foo(evt):
+                    print(f"I've clicked {evt.target} with id {evt.target.id}")
+                @when("click", selector="#bar_id")
+                def foo(evt):
+                    print(f"I've clicked {evt.target} with id {evt.target.id}")
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").click()
+        console_text = self.console.all.lines
+        self.wait_for_console("I've clicked [object HTMLButtonElement] with id foo_id")
+        assert "I've clicked [object HTMLButtonElement] with id foo_id" in console_text
+
+        self.page.locator("text=bar_button").click()
+        console_text = self.console.all.lines
+        self.wait_for_console("I've clicked [object HTMLButtonElement] with id bar_id")
+        assert "I've clicked [object HTMLButtonElement] with id bar_id" in console_text
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_two_when_decorators(self):
+        """When decorating a function twice, both should function"""
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <button class="bar_class">bar_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                @when("mouseover", selector=".bar_class")
+                def foo(evt):
+                    print(f"An event of type {evt.type} happened")
+            </py-script>
+        """
+        )
+        self.page.locator("text=bar_button").hover()
+        self.page.locator("text=foo_button").click()
+        self.wait_for_console("An event of type click happened")
+        assert "An event of type mouseover happened" in self.console.log.lines
+        assert "An event of type click happened" in self.console.log.lines
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_two_when_decorators_same_element(self):
+        """When decorating a function twice *on the same DOM element*, both should function"""
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                @when("mouseover", selector="#foo_id")
+                def foo(evt):
+                    print(f"An event of type {evt.type} happened")
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").hover()
+        self.page.locator("text=foo_button").click()
+        self.wait_for_console("An event of type click happened")
+        assert "An event of type mouseover happened" in self.console.log.lines
+        assert "An event of type click happened" in self.console.log.lines
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_when_decorator_multiple_elements(self):
+        """The @when decorator's selector should successfully select multiple
+        DOM elements
+        """
+        self.pyscript_run(
+            """
+            <button class="bar_class">button1</button>
+            <button class="bar_class">button2</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector=".bar_class")
+                def foo(evt):
+                    print(f"{evt.target.innerText} was clicked")
+            </py-script>
+        """
+        )
+        self.page.locator("text=button1").click()
+        self.page.locator("text=button2").click()
+        self.wait_for_console("button2 was clicked")
+        assert "button1 was clicked" in self.console.log.lines
+        assert "button2 was clicked" in self.console.log.lines
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_when_decorator_duplicate_selectors(self):
+        """ """
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#foo_id")
+                @when("click", selector="#foo_id")
+                def foo(evt):
+                    print(f"I've clicked {evt.target} with id {evt.target.id}")
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").click()
+        console_text = self.console.all.lines
+        self.wait_for_console("I've clicked [object HTMLButtonElement] with id foo_id")
+        assert (
+            console_text.count("I've clicked [object HTMLButtonElement] with id foo_id")
+            == 2
+        )
+        self.assert_no_banners()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_when_decorator_invalid_selector(self):
+        """When the selector parameter of @when is invalid, it should show an error"""
+        self.pyscript_run(
+            """
+            <button id="foo_id">foo_button</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#.bad")
+                def foo(evt):
+                    ...
+            </py-script>
+        """
+        )
+        self.page.locator("text=foo_button").click()
+        msg = "Failed to execute 'querySelectorAll' on 'Document': '#.bad' is not a valid selector."
+        error = self.page.wait_for_selector(".py-error")
+        banner_text = error.inner_text()
+
+        if msg not in banner_text:
+            raise AssertionError(
+                f"Expected message '{msg}' does not "
+                f"match banner text '{banner_text}'"
+            )
+
+        assert any(msg in line for line in self.console.error.lines)

pyscriptjs/tests/integration/test_zzz_docs_snippets.py

@@ -209,3 +209,63 @@ class TestDocsSnippets(PyScriptTest):
         py_terminal = self.page.wait_for_selector("py-terminal")
 
         assert "0\n1\n2\n" in py_terminal.inner_text()
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_reference_when_simple(self):
+        self.pyscript_run(
+            """
+            <button id="my_btn">Click Me to Say Hi</button>
+            <py-script>
+                from pyscript import when
+                @when("click", selector="#my_btn")
+                def say_hello():
+                    print(f"Hello, world!")
+            </py-script>
+            """
+        )
+        self.page.get_by_text("Click Me to Say Hi").click()
+        self.wait_for_console("Hello, world!")
+        assert ("Hello, world!") in self.console.log.lines
+
+    @skip_worker(reason="FIXME: js.document (@when decorator)")
+    def test_reference_when_complex(self):
+        self.pyscript_run(
+            """
+            <div id="container">
+                <button>First</button>
+                <button>Second</button>
+                <button>Third</button>
+            </div>
+            <py-script>
+                from pyscript import when
+                import js
+
+                @when("click", selector="#container button")
+                def highlight(evt):
+                    #Set the clicked button's background to green
+                    evt.target.style.backgroundColor = 'green'
+
+                    #Set the background of all buttons to red
+                    other_buttons = (button for button in js.document.querySelectorAll('button') if button != evt.target)
+                    for button in other_buttons:
+                        button.style.backgroundColor = 'red'
+
+                    print("set") # Test Only
+            </py-script>
+            """
+        )
+
+        def getBackgroundColor(locator):
+            return locator.evaluate(
+                "(element) => getComputedStyle(element).getPropertyValue('background-color')"
+            )
+
+        first_button = self.page.get_by_text("First")
+        assert getBackgroundColor(first_button) == "rgb(239, 239, 239)"
+
+        first_button.click()
+        self.wait_for_console("set")
+
+        assert getBackgroundColor(first_button) == "rgb(0, 128, 0)"
+        assert getBackgroundColor(self.page.get_by_text("Second")) == "rgb(255, 0, 0)"
+        assert getBackgroundColor(self.page.get_by_text("Third")) == "rgb(255, 0, 0)"