Feature Request: Enhanced Method Naming Decorators for Better Developer Experience

[mrjk]

I'd like to propose adding optional decorator-based method naming to Textual that would improve developer experience while maintaining full backward compatibility with existing naming conventions.

Problem

While Textual's current naming convention system (e.g., on_<message_name> for message handlers) works well, it creates several developer experience challenges:

1. Search/Replace Difficulties: When searching for method references in code, the auto-generated on_ prefixed names are hard to find and replace consistently
2. Code Boilerplate Issues: During refactoring or string replacement, it's easy to miss methods that follow the naming convention but aren't directly visible in the source
3. API vs Application Logic Confusion: The distinction between Textual's API methods and application-specific logic becomes blurred
4. IDE Support: Some IDEs struggle with auto-completion and refactoring for dynamically named methods
5. Silent Refactoring Failures: Unrenamed methods following naming conventions are silently ignored during search/replace operations, leading to missed updates
6. @On decorator not universal: While it works well with messages, it does not provide support for action_* or watch_*

Proposed Solution

Add optional decorators that allow explicit method naming while maintaining the existing convention system:

from textual.decorators import message, action, watch

class MyWidget(Widget):
    @message(Button.Pressed)
    def handle_button_click(self, event: Button.Pressed) -> None:
        # Method is automatically renamed to on_button_pressed
        pass
    
    @action("save")
    def perform_save(self) -> None:
        # Method is automatically renamed to action_save
        pass
    
    @watch("count")
    def handle_count_change(self, new_value: int) -> None:
        # Method is automatically renamed to watch_count
        pass

Benefits

1. Backward Compatibility: Existing code continues to work unchanged
2. Better Searchability: Method names in source code match their actual names
3. Clearer Intent: Decorators make the relationship between methods and events explicit
4. Improved Refactoring: IDEs can better track method references
5. Optional Adoption: Developers can choose to use decorators or stick with conventions
6. Prevents Silent Failures: Explicit decorators ensure methods aren't missed during refactoring

Implementation

The decorators would:

• Automatically rename methods to follow Textual's conventions at class definition time
• Use the existing handler_name property from Message classes
• Support all existing Textual patterns (messages, actions, watches, more ?)
• Maintain the same functionality as current naming conventions

Example Implementation (POC)

Here's a proof of concept I've developed, but there are probably some stuffs to improve/change:

import inspect
import logging
from typing import Callable, TypeVar, Any
from functools import wraps
from textual.case import camel_to_snake
from textual.message import Message

logger = logging.getLogger(__name__)


def _create_renamed_method_decorator(name_generator: Callable) -> Callable:
    """
    Factory function that creates a method renaming decorator.
    
    Args:
        name_generator: Function that takes the decorator arguments and returns the new method name
    """
    def decorator(*args):
        def inner_decorator(func):
            class RenamedMethod:
                def __init__(self, func):
                    self.func = func
                    self.new_name = name_generator(*args)
                    logger.debug(f"Rename {func.__name__} to {self.new_name} via {name_generator.__name__}")

                def __get__(self, obj, objtype=None):
                    if obj is None:
                        return self.func
                    return self.func.__get__(obj, objtype)
                
                def __set_name__(self, owner, name):
                    # Rename the method in the class
                    setattr(owner, self.new_name, self.func)
                    if hasattr(owner, name):
                        delattr(owner, name)
            
            return RenamedMethod(func)
        return inner_decorator
    return decorator


def _message_name_generator(cls: type) -> str:
    """Generate handler name for message decorator."""
    return cls.handler_name


def _action_name_generator(name: str) -> str:
    """Generate action name for action decorator."""
    return f"action_{name}"


def _watch_name_generator(name: str) -> str:
    """Generate watch name for watch decorator."""
    return f"watch_{name}"


# Create the three decorators using the factory
message = _create_renamed_method_decorator(_message_name_generator)
action = _create_renamed_method_decorator(_action_name_generator)
watch = _create_renamed_method_decorator(_watch_name_generator)

Example

from textual.decorators import message, action, watch

class LdapEntrySelection(Message):
    """Message sent when an LDAP entry is selected in the tree."""
    def __init__(self, tree_view, node_data: dict):
        self.tree_view = tree_view
        self.node_data = node_data
        super().__init__()

class MyWidget(Widget):
    @message(LdapEntrySelection) # Instead of: on_ldap_entry_selection
    def handle_ldap_selection(self) -> str:
        # Method is automatically renamed to on_ldap_entry_selection
        return "data"
    
    @action("save") # Instead of: action_save
    def perform_save_operation(self) -> str:
        # Method is automatically renamed to action_save
        return "saved"

Limitations

Static Linting: The decorator approach may occasionally break static linting tools that expect methods to have their final names at definition time. However, this is typically a minor issue as most linting tools work with the runtime method names. The benefits of explicit naming generally outweigh this consideration.

Discussion Reference

This builds on the existing discussion about method naming patterns: #2632

Conclusion

This feature would enhance developer experience without breaking existing code, making Textual applications easier to maintain and refactor while preserving the elegant convention-based approach that makes Textual so powerful. Even if @on partially answer this question, it does not seem to work on all textual methods/events (to be confirmed).

---

Note: This proposal has been rephrased with the assistance of AI to ensure clarity and proper technical communication.

[TomJGooding]

https://textual.textualize.io/guide/events/#on-decorator

EDIT: I missed this with all the other AI assisted "clarity", but this proposal really just boils down to:

@on decorator not universal: While it works well with messages, it does not provide support for action_* or watch_*

[willmcgugan]

@mrjk Your implementation of action and watch decorators is problematic. Consider what would happen if you subclass a widget with these decorators. If you don't reapply the decorator in the subclass, then it won't work as expected.

I also think that that dynamic name changing is going to confuse LSPs rather than make it better.

Decorators in general are problematic because they don't inherit. If your decorator takes a reference to the method and invokes it later, then it will call the method on the base class and not on the subclass.

The @on decorator has different semantics. Messages go to each method on all subclasses (unless you call event.prevent_default). So keeping a reference to the method is desirable.

The naming convention is honestly completely fine. No surprises as they are regular methods. Ultimately they are the least astonishing of the alternatives.

[mrjk]

Hey, thanks for your feedback :)

From your points:

• Indeed, decorators does not work well with inheritance, but since here since I modify the class itself (and not the instance), maybe it's propagated to its subclasses? Otherwise, I would just consider this as a general decorator limitation, and in this case, I may not recommend to use decorators. (I'm not expert enough in python to answer without testing first)
• Dynamic name changes do confuse LSPs, and ... I quickly tried to workaround with that before finally giving up. Also, I realized (but maybe I'm wrong, it may depends on how developers code) I found uncommon to call directly those function; and if you need to, we can still use the old unwrapped name (in this case, we need to update above implementation to keep old name, which could make sense).
• On the actual @on semantic, I got into the code; but I still have difficulties to understand the whole system implementation. (That's why I'm posting a proposal and not a PR :p). I did not really pay attention/understood to the fact there were references in current implementation. My initial intention was to simply extend current @on implementation, but I did not succeeded to make a working POC. However, yeah, the current implementation is probably not the best ^^
• Current naming convention is actually pretty smart; I like it pretty much as well, but it also comes with drawbacks. Eventually I'm the only developer to hit those drawbacks, but eventually I'm not. I feel like providing two APIs for this use case would make sense, especially by helping textual to help developers to go faster, and to use the correct tools for their own use cases.

@TomJGooding : Haha, you actually highlighted one of the very few sentences I added after I rephrased with AI. But yeah, you got the exact point :D