Alternate (Elm inspired) message handling using PEP 636 Structural Pattern Matching

[davetapley]

Context

The docs say for custom messages:

The message class is defined within the widget class itself. This is not strictly required but recommended, for these reason
...
It creates a namespace for the handler. So rather than on_selected, the handler name becomes on_color_button_selected.

And reiterated in the section on handling messages:

Textual uses the following scheme to map messages classes on to a Python method.
Add the messages' namespace (if any) converted from CamelCase to snake_case plus an underscore "_"
Add the name of the class converted from CamelCase to snake_case.

Problem

Message handlers are very sensitive to refactoring:

1. Any renaming (using an IDE or manual) could result in handlers no longer being called.
2. Bubbling means the handler could be quite 'far away' from the refactor.
3. It will 'fail silently' since the handler will just stop being called.

Arguably comprehensive testing should catch such errors, but it still makes for an awkward developer experience.

How Elm does this

I am reminded of the message handling in Elm, which solves a similar problem but in a different way, specifically:

1. All 'messages' come in on a single update method, and:
2. Because the type of the messages are know, the compiler can warn you if you missed one.

Proposal part 1

make renaming easier

Give Widget and App an update method which would receive all messages.

This would be called as well as the current magically named methods, allowing gradual adoption.

Inside the update method the developer could use PEP 636 Structural Pattern Matching as shown here to handle different messages.

This would provide a common entry point for handlers, and so automated renaming of Message sub-classes wouldn't break handlers.

Proposal part 2

strict mode for unhandled messages

Instead of implementing an update method, the developer could annotate handler methods with a decorator (and any appropriate method name). Textual would dispatch incoming messages to the appropriate handler.

Textual could then (optionally) warn or throw when a Widget or App doesn't handle a message.
The developer could then check whether the message is intentionally unhandled, and change bubbling or add a handler as appropriate.

[willmcgugan]

Having all messages go through a common method would create boilerplate code, which I want to avoid. It would also encourage Textual devs to implement their own ad-hoc message dispatch mechanism. Even if you are running on Python 3.10 and can use the match statement, it is still easy to get wrong.

I take your point re refactoring, but changing the name of an event would likely necessitate changing the method name anyway.

I'm guessing you haven't seen the new @on decorator.

[davetapley]

I had not seen @on, very nice!

That will definitely make renaming of the Message subclass safer, although this makes me nervous again:

the main advantage of the decorator approach over the naming convention is ...
...
The on decorator takes a CSS selector in addition to the event type which will be used to select which controls the handler should work with

Similar to my initial concern, that means that changing an ID or class name could cause easy-to-miss bugs.

I feel like interrogating type-checkable attributes on the Message sub-class to decide whether (and how) to handle is safer.
Although, I think your position would be that is encouraging boilerplate again?

---

changing the name of an event would likely necessitate changing the method name anyway

I'm not sure. Few times I've run in to this I was renaming a widget (to extract to different module) and in doing so inadvertently broke handler up the tree because the name no longer matched (but the semantics were still the same).

@on definitely helps with this, though ✅

---

Great library BTW, love it and has been a pleasure to use, I just 💜 Haskell so please forgive my always pushing for more type safety 😁