Merge pull request #22 from sirfuzzalot/feat/custom-message-names

feat: custom message names

Author: sirfuzzalot

README.md

@@ -7,10 +7,60 @@
 
 Textual Inputs is a collection of input widgets for the [Textual](https://github.com/willmcgugan/textual) TUI framework.
 
-⚠️ This library is experimental and its interfaces are likely
-to change, much like the underlying Textual library.
+> ⚠️ This library is experimental and its interfaces will change. While
+> Textual Inputs is pre-alpha please pin your projects to the minor release
+> number to avoid breaking changes. For example: textual-inputs=0.2.\*
 
-## Supported Widgets
+---
+
+## News
+
+### v0.2.4
+
+Adds support for customizing the message handler names for on change and
+on focus events emitted by the inputs. Under the hood this will generate
+a `Message` class with the appropriate name for Textual to send it to
+the handler name provided. You'll then want add the handler to the input's
+parent or the App instance. If you opt not to customize these handlers,
+their values will be the default `handle_input_on_change` and `handle_input_on_focus`.
+See `examples/simple_form.py` for a working example.
+
+```python
+email = TextInput(name="email", title="Email")
+email.on_change_handler_name = "handle_email_on_change"
+email.on_focus_handler_name = "handle_email_on_focus"
+```
+
+---
+
+## Quick Start
+
+Installation
+
+```bash
+python -m pip install textual-inputs=0.2.*
+```
+
+To use Textual Inputs
+
+```python
+from textual_inputs import TextInput, IntegerInput
+```
+
+Checkout the [examples](https://github.com/sirfuzzalot/textual-inputs/tree/main/examples) for reference.
+
+```bash
+git clone https://github.com/sirfuzzalot/textual-inputs.git
+cd textual-inputs
+python3 -m venv venv
+source venv/bin/activate
+python -m pip install -e .
+python examples/simple_form.py
+```
+
+---
+
+## Widgets
 
 ### TextInput 🔡
 
@@ -30,25 +80,105 @@ to change, much like the underlying Textual library.
 - controls: arrow right/left, home, end, delete, backspace/ctrl+h, escape
 - emits - InputOnChange, InputOnFocus messages
 
-## Quick Start
+---
 
-```bash
-python -m pip install textual-inputs
-```
+## API Reference
 
-Checkout the [examples](https://github.com/sirfuzzalot/textual-inputs/tree/main/examples) for reference.
+Textual Inputs has two widgets, here are their attributes.
 
-```bash
-git clone https://github.com/sirfuzzalot/textual-inputs.git
-cd textual-inputs
-python3 -m venv venv
-source venv/bin/activate
-python -m pip install -r requirements.txt
-python examples/simple_form.py
-```
+```python
+class TextInput(Widget):
+    """
+    A simple text input widget.
 
-To use Textual Inputs
+    Args:
+        name (Optional[str]): The unique name of the widget. If None, the
+            widget will be automatically named.
+        value (str, optional): Defaults to "". The starting text value.
+        placeholder (str, optional): Defaults to "". Text that appears
+            in the widget when value is "" and the widget is not focused.
+        title (str, optional): Defaults to "". A title on the top left
+            of the widget's border.
+        password (bool, optional): Defaults to False. Hides the text
+            input, replacing it with bullets.
+
+    Attributes:
+        value (str): the value of the text field
+        placeholder (str): The placeholder message.
+        title (str): The displayed title of the widget.
+        has_password (bool): True if the text field masks the input.
+        has_focus (bool): True if the widget is focused.
+        cursor (Tuple[str, Style]): The character used for the cursor
+            and a rich Style object defining its appearance.
+        on_change_handler_name (str): name of handler function to be
+            called when an on change event occurs. Defaults to
+            handle_input_on_change.
+        on_focus_handler_name (name): name of handler function to be
+            called when an on focus event occurs. Defaults to
+            handle_input_on_focus.
+
+    Events:
+        InputOnChange: Emitted when the contents of the input changes.
+        InputOnFocus: Emitted when the widget becomes focused.
+
+    Examples:
+
+    .. code-block:: python
+
+        from textual_inputs import TextInput
+
+        email_input = TextInput(
+            name="email",
+            placeholder="enter your email address...",
+            title="Email",
+        )
+
+    """
+```
 
 ```python
-from textual_inputs import TextInput, IntegerInput
+class IntegerInput(Widget):
+    """
+    A simple integer input widget.
+
+    Args:
+        name (Optional[str]): The unique name of the widget. If None, the
+            widget will be automatically named.
+        value (Optional[int]): The starting integer value.
+        placeholder (Union[str, int, optional): Defaults to "". Text that
+            appears in the widget when value is "" and the widget is not focused.
+        title (str, optional): Defaults to "". A title on the top left
+            of the widget's border.
+
+    Attributes:
+        value (Union[int, None]): the value of the input field
+        placeholder (str): The placeholder message.
+        title (str): The displayed title of the widget.
+        has_focus (bool): True if the widget is focused.
+        cursor (Tuple[str, Style]): The character used for the cursor
+            and a rich Style object defining its appearance.
+        on_change_handler_name (str): name of handler function to be
+            called when an on change event occurs. Defaults to
+            handle_input_on_change.
+        on_focus_handler_name (name): name of handler function to be
+            called when an on focus event occurs. Defaults to
+            handle_input_on_focus.
+
+    Events:
+        InputOnChange: Emitted when the contents of the input changes.
+        InputOnFocus: Emitted when the widget becomes focused.
+
+    Examples:
+
+    .. code-block:: python
+
+        from textual_inputs import IntegerInput
+
+        age_input = IntegerInput(
+            name="age",
+            placeholder="enter your age...",
+            title="Age",
+        )
+
+    """
 ```

examples/simple_form.py

@@ -1,4 +1,8 @@
 # app.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import rich.box
 from rich.panel import Panel
 from rich.style import Style
@@ -11,17 +15,20 @@
 
 from textual_inputs import IntegerInput, TextInput
 
+if TYPE_CHECKING:
+    from textual.message import Message
+
 
 class CustomHeader(Header):
     """Override the default Header for Styling"""
 
     def __init__(self) -> None:
         super().__init__()
         self.tall = False
+        self.style = Style(color="white", bgcolor="rgb(98,98,98)")
 
     def render(self) -> Table:
         header_table = Table.grid(padding=(0, 1), expand=True)
-        header_table.style = Style(color="white", bgcolor="rgb(98,98,98)")
         header_table.add_column(justify="left", ratio=0, width=8)
         header_table.add_column("title", justify="center", ratio=1)
         header_table.add_column("clock", justify="right", width=8)
@@ -62,7 +69,7 @@ def make_key_text(self) -> Text:
         return text
 
 
-class Demo(App):
+class SimpleForm(App):
 
     current_index: Reactive[int] = Reactive(-1)
 
@@ -88,22 +95,26 @@ async def on_mount(self) -> None:
             placeholder="enter your username...",
             title="Username",
         )
+        self.username.on_change_handler_name = "handle_username_on_change"
+
         self.password = TextInput(
             name="password",
             title="Password",
             password=True,
         )
+
         self.age = IntegerInput(
             name="age",
             placeholder="enter your age...",
             title="Age",
         )
+        self.age.on_change_handler_name = "handle_age_on_change"
+
         self.output = Static(
             renderable=Panel(
                 "", title="Report", border_style="blue", box=rich.box.SQUARE
             )
         )
-
         await self.view.dock(self.output, edge="left", size=40)
         await self.view.dock(self.username, self.password, self.age, edge="top")
 
@@ -134,12 +145,15 @@ async def action_reset_focus(self) -> None:
         self.current_index = -1
         await self.header.focus()
 
-    async def handle_input_on_change(self, message) -> None:
-        self.log(f"Input: {message.sender.name} changed")
+    async def handle_username_on_change(self, message: Message) -> None:
+        self.log(f"Username Field Contains: {message.sender.value}")
+
+    async def handle_age_on_change(self, message: Message) -> None:
+        self.log(f"Age Field Contains: {message.sender.value}")
 
-    async def handle_input_on_focus(self, message) -> None:
+    async def handle_input_on_focus(self, message: Message) -> None:
         self.current_index = self.tab_index.index(message.sender.name)
 
 
 if __name__ == "__main__":
-    Demo.run(title="Textual-Inputs Demo", log="textual.log")
+    SimpleForm.run(title="Textual-Inputs Demo", log="textual.log")

requirements.txt

@@ -33,7 +33,7 @@ package_dir =
 packages = find:
 python_requires = >=3.7
 install_requires =
-    textual >= 0.1.11,< 0.2
+    textual >= 0.1.14,< 0.2
 
 [options.packages.find]
 where = src

setup.cfg

@@ -1,6 +1,6 @@
 from .integer_input import IntegerInput
 from .text_input import TextInput
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 __all__ = ["IntegerInput", "TextInput"]

src/textual_inputs/__init__.py

@@ -1,16 +1,67 @@
 """
 Events for Textual-Inputs
 """
+from __future__ import annotations
+
+from string import ascii_lowercase, digits
+
 from textual.message import Message
 
+HANDLER_SAFE = ascii_lowercase + digits + "_"
+
 
 class InputOnChange(Message, bubble=True):
-    """Emitted when the value of an input changes"""
+    """Generic on change message for inputs"""
 
-    pass
+    _handler: str = "handle_input_on_change"
 
 
 class InputOnFocus(Message, bubble=True):
-    """Emitted when the input becomes focused"""
+    """Generic on focus message for inputs"""
+
+    _handler: str = "handle_input_on_focus"
+
+
+def make_message_class(handler_name: str) -> Message:
+    """
+    Produces an appropriately named Message subclass that will call the
+    handler with the same name as handler_name.
+
+    Args:
+        handler_name (str): handler function name. Must start with "handle_" and
+            contain only lowercase ASCII letters, numbers and underscores.
+
+    Returns:
+        Message: a subclass of the Message class.
+
+    Raises:
+        ValueError: handler_name must start with 'handle_'.
+        ValueError: handler_name must contain only lowercase ASCII
+            letters, numbers and underscores.
+
+    Example:
+
+    .. code-block:: python
+
+        >>>make_message_class("handle_username_on_change")
+        <class 'textual_inputs.events.username_on_change>
+        >>>def handle_username_on_change(self, event: Message) -> None:
+
+    """
+    if not handler_name.startswith("handle_"):
+        raise ValueError("handler_name must start with 'handle_'")
+
+    if len(handler_name) < 7:
+        raise ValueError("handler_name must be greater than 7 characters")
 
-    pass
+    for char in handler_name:
+        if char not in HANDLER_SAFE:
+            raise ValueError(
+                "handler_name must contain only lowercase ASCII letters, "
+                + "numbers and underscores."
+            )
+    name = handler_name.lower()[7:]
+    t = type(name, (Message,), {})
+    t._handler = handler_name
+    t.bubble = True
+    return t