As we are discussing to refactor our API I'd like to make my point around the (personal) ideal @when signature:

@when(whenable[, options[, rest]])

Using previous examples that means that adding multiple listeners to a button, that currently looks like this:

b = button("Click me")

@when("click", b)
@when("dblclick", b)
def handle_click(click_event):
    ...

moving the target/subject before could instead like:

@when(b, "click")
@when(b, "dblclick")

# or ...

@when(b, ["click", "dblclick"])

The protocol can easily be implemented in our DOM API or literally anything else and we could have explicit names that don't even require a string contract with the underlying logic:

@when(geo_position)
def handle_coords():
   ...

That could be triggerd for updates, one off results, or errors ... which are 3 different cases to handle ... writing this instead:

@when("update", geolocation)
def handle_maybe(result):
   ....

requires geolocation whenable to understand the "update" string but then if there is an error, a timeout, whatever really, we need to implement other 3 strings to handle and users need to learn those strings + API of the geolocation instead of just whenning a geolocation reference and deal with the result as they please ... so we currently would have:

@when("update", geolocation)
@when("errored", geolocation)
@when("current", geolocation)
def handle_maybe(result):
    if isinstance(result, Exception):
        ....
    elif result.accuracy < threshold:
        ...
    else:
        ....

The logic in that callback would remain identical if we had only:

@when(geolocation)
def handle_geolocation(result):
    # same logic as before

Moreover, we could preserve the current state of affair for backward compatibility reasons by simply providing events name as references, instead of strings:

@when(user.click, b)
def handle_click(event):
    ....

# or ....
@when(user.click, [b, c, d])
# keeping the "whenable" first

In short, I really don't think strings are necessary or improve much, they actually create an obligatory understanding of such strings from the whenable reference or protocol so I think we could do better.

Speaking strictly about DOM though, the rest of the JS world uses @on decorator instead, which instantly signals it's going to be an event signature and behavior (by convention, of course, as in @on(b, "click")) but I see @when potentially being way more than just events added, also because there is no @unwhen counterpart for events at all ... which is not super fine but I guess we lived with that until now.

This is such a fascinating feature.

I was describing it to Damien last week, and he asked, "why not just await?" to which I replied, "the @when decorator helps avoid asyncio related encounters in a way that is friendly for inexperienced coders, but convenient for everyone else".

This brings up an interesting point: @when should understand if it is decorating an awaitable or a callable (i.e. it should make no difference). I also wonder if @when should act as both a decorator and a function... because decorators can be mysterious "it just works like that" features of Python to inexperienced developers. So...

def do_something(result):
    ...

when(something.happens, do_something)

Should be equivalent to:

@when(something.happens):
def do_something(result):
    ...

With my pedagogue's hat on: it's easier to explain the first example ("you're just calling a function to associate some future event with a function to handle the result"), rather than have to hand-wave over the use of a decorator ("it's just like that", is never a phrase a learner should have to accept). Rather, the use of @when as a decorator is a graduation step to a "short-cut" feature of the language. Of course, this has no impact on experienced Pythonistas, or coders who may be coming from other languages and understand the concept of a first-class function already. But, y'know... for the 99% means we should consider this.

I like the concept of just passing in a when-able, rather than (as happens now in the context of the DOM API) a string containing the name of an event, and an object in the DOM through which the event bubbles.

But this requires thought about two things:

• How do we transition from the current @when if at all? There is a wrinkle here since the current version of @when can take an object that is both a pyscript.web based thing, and a JSProxy object from the underlying API. We can update the pyscript.web namespace to behave properly, but the JSProxy is going to be problematic.
• The behaviour of when-able objects, and how this relates to the use of the function/decorator @when.

I think @WebReflection's proposed signature of, @when(whenable[, options[, rest]]) is a good place to start. I'd revise this to a more Pythonic, @when(whenable, *args, **kwargs). If the first item in *args or the object with the key function in **kwargs is callable/awaitable, then when is being called as a simple function (when(whenable, function=my_fn)). Remaining *args and **kwargs are passed into the __when__ dunder-method as context. For reasons that will become clear in a moment, such functions should take a single argument representing the result created when "the thing" happened. As a result, the two examples given above "should just work" ™️.

I guess the __when__ dunder-method of the when-able simply takes the handling function, along with *args and **kwargs and the rest is just implementation details depending on context.

On that note... handling errors. I like @WebReflection's suggested pattern of checking if the result passed into the function is an instance of a Python Exception and then leaving it to the writer of the handling function: we've indicated how they can determine the status of the result, and they have the freedom to do as they please.

I think we're getting close[r] now, and I like the simplicity of how things work. I wonder if we've overlooked anything? I'd like to bring this discussion to the community call tomorrow. My concern is the current @when dealing with JSProxy objects. All feedback welcome.

cc/ @fpliger @mchilvers

Not sure if my concern with original @when still exists.
Specifically my concern was:

• I dynamically add a new (say) Div to the dom. I want a mouseover to trigger some action. I can't use a decorator because I added the Div dynamically. There is no code to decorate. What happens when I dynamically remove the Div from the dom?
• would I use .on() like the ltk, or .on() mirroring how JS does it, or bind it to a new class in some way and give that a __when__(self) method or do a puepy kind of approach (which is derived from a Vue2 like concept).
• @whenever was also briefly proposed at one stage...

A non-functioning code example of how it would be used in several usecases would be great...

@Neon22 these are excellent points. Briefly (I'm about to step into a meeting), having when function as both a decorator and "vanilla" function means you could do something like:

def do_something(result):
    ...

# Dynamically create a thing.
b = pyscript.web.button("Click Me!")

# b.click is a "when-able"
when(b.click, do_something)

pyscript.web.page.append(b)

Does this help..?

Something else to ponder...

We have been concentrating on how to link events and handlers via when. However, we've not discussed how to un-link them when such association is no longer needed. Clearly, if the when-able object no longer exists, stuff will be GC'd. However, there may be cases where we no longer want to handle events from a long-running when-able. For example, there might be a geo-location object that has a location_changed when-able, that fires at various moments in the future depending on if the geo-location of the device has changed. I can imagine wanting to handle and then not handle such updates (and then re-handle them) depending on the state of an app (e.g. you're in "live map mode", or something).

I suggest that when-ables should also have a clear method that takes optional arguments of handlers. If the handler is already attached to the when-able, it is removed. If no handlers are passed into clear all handlers are removed.

For example, a numpty off-the-top-of-my-head example:

class MyWhenable:

    def __init__(self):
        self.handlers = []

    def trigger(self):
        for handler in self.handlers:
            handle({"result": "ok"})

    def __when__(self, handler, *args, **kwargs):
        self.handlers.append(handler)

    def clear(self, *args):
        if args:
            for h in args:
                self.handlers.remove(h)
        else:
            self.handlers = []

def my_handler(result):
    ... do stuff ...

whenable = MyWhenable()

when(whenable, my_handler)

... time passes ...

# No longer needed.
whenable.clear(my_handler)

Thoughts..?

Another thought... perhaps we're over thinking this?

We don't need a fancy-smansy "protocol" with a dunder-when. Perhaps we just need to provide a pyscript.Effect class that folks can override as they see fit, and which the @when decorator understands:

class Effect:
    """
    Represents something (a side effect) that may happen at some point in the future.
    """
    
    def __init__(self):
        self._handlers = {}  # key: id(handler), value: callable, args, kwargs

    def trigger(self):
        """
        Trigger the effect to create an event to pass into the handlers.

        E.g.:
        
        event = {"message": "ok"}
        for handler in self._handlers.values():
            handler["callable"](event, *handler["args"], **handler["kwargs"])
        """
        raise NotImplementedError("Child class to override this method.")

    def when(self, handler_function, *args, **kwargs):
        self._handlers[id(handler)] = {
            "callable": handler_function,
            "args": args,
            "kwargs": kwargs,
        }

    def clear(self, *args):
        """"
        Clear the specified handler functions in *args. If no handlers provided, clear all handlers.
        """"
        if args:
            for handler in args:
                self._handlers.pop(id(handler), None)
        else:
            self._handlers = {}

But then, I can't help but wonder if we're not just re-inventing a very simple version of promises/futures/deferreds..?

Thoughts?

OK folks, I've stacked some changes into a new branch that makes use of an Event object. What's more, and just for "fun", I've ensured that any pyscript.web Element instance returns any onFOO attributes as Event instances, so you can do things like:

b = button("Click me")

@when(b.onclick)
def handler(ev):
    ... handle the "click" event...

Also, the Event class is a nicely encapsulated "thing" that manages adding/removing listeners, and only by calling the object's trigger method with a single result will the handlers be called:

e = Event()

def example_listener(result):
    ...

e.add_listener(example_listener)

e.trigger({"some": "arbitrary result"})  # The single argument into trigger is passed into all the registered handlers.

e.remove_listener(example_listener)  # Remove the specific listener.
e.remove_listener()  # Remove all listeners.

As always, this is an experiment and I'd welcome feedback, ideas and constructive critique!

Just listened to the youtube discussion. - https://youtu.be/_zbM5YtKrVA?t=2219

Good question from Martin about do we pass event arg through. IMHO we need to do this (have an event arg).
Why - because I do have a single handler for 200 buttons because they are all implemented as an svg rect and I parse the event and determine which virtual button was hit based on the click coords. I do this in a mouseover for responsiveness and not having thousands of dom ids

Readable is important but making it impossible for me to implement apparent complexity easily is also important.
You could use "None" for the event or default to None. Then maybe both cases will work