Allow to use Reactive class-var attr in watch method

[uriyyo]

Currently, when using DOMNode.watch() to observe reactive attributes on other widgets, you must pass the attribute name as a string:

self.watch(my_widget, "counter", self.on_counter_changed)

It's nice and easy, but unfortunately, it's not properly integrated with type-checkers.

Let me show a situation that I faced:

from textual.app import App, ComposeResult
from textual.reactive import reactive
from textual.widgets import Label, Button


class Counter(Label):
    count: reactive[int] = reactive(0)

    def render(self) -> str:
        return f"Count: {self.count}"


class CounterApp(App):
    def compose(self) -> ComposeResult:
        yield Counter(id="counter")
        yield Button("Increment", id="increment")

    def on_mount(self) -> None:
        counter = self.query_one(Counter)

        # typo in attribute name - "coutn" instead of "count"
        self.watch(counter, "coutn", self.on_count_changed)

    def on_count_changed(self, value: int) -> None:
        self.notify(f"Counter changed to {value}")

    def on_button_pressed(self, event: Button.Pressed) -> None:
        counter = self.query_one(Counter)
        counter.count += 1

So, I basically made a typo and was able to find it only at runtime; there were no linter errors.

I propose to allow use Reactive class-var attr in watch method, so example above will look like this:

    def on_mount(self) -> None:
        counter = self.query_one(Counter)

        # updated: using Reactive class-var directly
        # - IDE autocomplete helps you pick the right attribute
        # - Type checkers catch typos immediately
        # - Refactoring tools update references automatically
        self.watch(counter, Counter.count, self.on_count_changed)

You can even add additional checks that will make sure that you are using Reactive class-var attr from the correct class:

from textual.app import App, ComposeResult
from textual.reactive import reactive
from textual.widget import Widget
from textual.widgets import Button, Label, ProgressBar


class Counter(Widget):
    DEFAULT_CSS = "Counter { height: auto; }"
    counter = reactive(0)

    def compose(self) -> ComposeResult:
        yield Label()
        yield Button("+10")

    def on_button_pressed(self) -> None:
        self.counter += 10

    def watch_counter(self, counter_value: int):
        self.query_one(Label).update(str(counter_value))


class CounterChild(Counter):
    pass


class OtherCounter(Widget):
    DEFAULT_CSS = "OtherCounter { height: auto; }"
    counter = reactive(0)
    label = reactive("")

    def compose(self) -> ComposeResult:
        yield Label()
        yield Button("+5")

    def on_button_pressed(self) -> None:
        self.counter += 5

    def watch_other_counter(self, other_counter_value: int):
        self.query_one(Label).update(str(other_counter_value))


class WatchApp(App[None]):
    def compose(self) -> ComposeResult:
        yield Counter()
        yield ProgressBar(total=100, show_eta=False)

    def on_mount(self):
        def update_progress(counter_value: int):
            self.query_one(ProgressBar).update(progress=counter_value)

        # good: Counter is the exact class of the instance
        self.watch(self.query_one(CounterChild), CounterChild.counter, update_progress)

        # good: Counter is base class of CounterChild
        self.watch(self.query_one(CounterChild), Counter.counter, update_progress)

        # bad: OtherCounter is unrelated to CounterChild, even though the property names match
        self.watch(self.query_one(CounterChild), OtherCounter.counter, update_progress)

        # bad: OtherCounter is unrelated to CounterChild and property types don't match
        self.watch(self.query_one(CounterChild), OtherCounter.label, lambda v: None)

I already implemented this feature, and now ty will give you an error for invalid usage:

error[invalid-argument-type]: Argument to bound method `watch` is incorrect
  --> temp.py:58:50
   |
57 |         # bad: OtherCounter is unrelated to CounterChild, even though the property names match
58 |         self.watch(self.query_one(CounterChild), OtherCounter.counter, update_progress)
   |                                                  ^^^^^^^^^^^^^^^^^^^^ Expected `Reactive[Any, CounterChild] | str`, found `Unknown | Reactive[int, OtherCounter]`
59 |
60 |         # bad: OtherCounter is unrelated to CounterChild and property types don't match
   |
info: Element `Reactive[int, OtherCounter]` of this union is not assignable to `Reactive[Any, CounterChild] | str`
info: Method defined here
    --> src/textual/dom.py:1253:9
     |
1251 |         return cast("list[DOMNode]", nodes)
1252 |
1253 |     def watch(
     |         ^^^^^
1254 |         self,
1255 |         obj: ReactableType,
1256 |         attribute_name: Reactive[Any, ReactableType] | str,
     |         -------------------------------------------------- Parameter declared here
1257 |         callback: WatchCallbackType,
1258 |         init: bool = True,
     |
info: rule `invalid-argument-type` is enabled by default

error[invalid-argument-type]: Argument to bound method `watch` is incorrect
  --> temp.py:61:50
   |
60 |         # bad: OtherCounter is unrelated to CounterChild and property types don't match
61 |         self.watch(self.query_one(CounterChild), OtherCounter.label, lambda v: None)
   |                                                  ^^^^^^^^^^^^^^^^^^ Expected `Reactive[Any, CounterChild] | str`, found `Unknown | Reactive[str, OtherCounter]`
   |
info: Element `Reactive[str, OtherCounter]` of this union is not assignable to `Reactive[Any, CounterChild] | str`
info: Method defined here
    --> src/textual/dom.py:1253:9
     |
1251 |         return cast("list[DOMNode]", nodes)
1252 |
1253 |     def watch(
     |         ^^^^^
1254 |         self,
1255 |         obj: ReactableType,
1256 |         attribute_name: Reactive[Any, ReactableType] | str,
     |         -------------------------------------------------- Parameter declared here
1257 |         callback: WatchCallbackType,
1258 |         init: bool = True,
     |
info: rule `invalid-argument-type` is enabled by default

Found 2 diagnostics

Let me know what do you think about this feature.

[willmcgugan]

That would be fine. It should continue to work with the string to maintain backwards compatibility.

[uriyyo]

Nice, here is PR with implementation - #6331

[willmcgugan]

It's marked as draft. Is it ready to review?

[uriyyo]

Sorry, yes it's ready for review, forget to update PR status