textual-wtf 0.8.0__py3-none-any.whl

textual_wtf/validators.py

@@ -0,0 +1,40 @@
+"""Validators for form fields"""
+import re
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+from textual.validation import Validator, ValidationResult
+
+
+SIMPLE_EMAIL_PAT = re.compile(r".+\@.+\..+")
+
+
+class EvenInteger(Validator):
+    """Example custom validator - validates even integers"""
+
+    def validate(self, value: str) -> ValidationResult:
+        try:
+            int_value = int(value)
+        except ValueError:
+            return self.success()
+
+        if int_value % 2 != 0:
+            return self.failure("Must be an even number")
+        return self.success()
+
+
+class Palindromic(Validator):
+    """Example custom validator - validates palindromes"""
+
+    def validate(self, value: str) -> ValidationResult:
+        if value == value[::-1]:
+            return self.success()
+        return self.failure("Must be a palindrome")
+
+
+class EmailValidator(Validator):
+    """Simple email validator - rejects addresses like 'user@name' without TLD"""
+
+    def validate(self, value: str) -> ValidationResult:
+        if not value or not SIMPLE_EMAIL_PAT.match(value):
+            return self.failure("Must be a valid email address")
+        return self.success()

textual_wtf/version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

textual_wtf/widgets.py

@@ -0,0 +1,165 @@
+"""Form widgets with validation support"""
+from typing import List, Optional, TYPE_CHECKING, Tuple
+from textual.widgets import Input, Checkbox, Select, TextArea, Static
+from textual.containers import Center
+from textual.validation import ValidationResult, Validator
+
+if TYPE_CHECKING:
+    from .fields import Field
+
+
+def widget_id_gen():
+    """Generate unique widget IDs"""
+    count = 0
+    while True:
+        count += 1
+        yield f"field-widget-{count}"
+
+
+_id_gen = widget_id_gen()
+
+
+class FormWidgetMixin:
+    """Mixin to add validation error display to widgets"""
+    
+    async def on_input_changed(self, event):
+        """Handle input changes and display validation errors"""
+        if not hasattr(self, 'parent') or self.parent is None:
+            return
+        
+        container = self.parent
+        
+        # ALWAYS clear previous errors first
+        await container.remove_children(".form-error")
+        
+        if hasattr(event, 'validation_result') and event.validation_result is not None:
+            vr = event.validation_result
+            if not vr.is_valid:
+                # Show all errors from this validation
+                for msg in vr.failure_descriptions:
+                    container.mount(Center(Static(msg), classes="form-error"))
+
+
+class FormInput(Input, FormWidgetMixin):
+    """Text input widget for forms"""
+    
+    def __init__(self, *, field: Optional['Field'] = None, valid_empty: bool = True,
+                 validators: Optional[List[Validator]] = None, **kwargs):
+        kwargs.setdefault('id', next(_id_gen))
+        kwargs['validators'] = validators or []
+        super().__init__(**kwargs)
+        self.field = field
+        self.valid_empty = valid_empty
+
+
+class FormIntegerInput(Input, FormWidgetMixin):
+    """Integer input widget for forms"""
+    
+    def __init__(self, *, field: Optional['Field'] = None, valid_empty: bool = True,
+                 validators: Optional[List[Validator]] = None, **kwargs):
+        kwargs.setdefault('id', next(_id_gen))
+        kwargs['type'] = 'integer'
+        kwargs['validators'] = validators or []
+        super().__init__(**kwargs)
+        self.field = field
+        self.valid_empty = valid_empty
+
+
+class FormTextArea(TextArea, FormWidgetMixin):
+    """Multi-line text area widget for forms"""
+    
+    def __init__(self, *, field: Optional['Field'] = None, text: str = "", **kwargs):
+        kwargs.setdefault('id', next(_id_gen))
+        super().__init__(text=text, **kwargs)
+        self.field = field
+    
+    @property
+    def value(self):
+        """Get text area value"""
+        return self.text
+    
+    @value.setter
+    def value(self, v):
+        """Set text area value"""
+        self.text = v if v is not None else ""
+    
+    def validate(self, value):
+        """Validate text area value"""
+        return ValidationResult()
+
+
+class FormCheckbox(Checkbox):
+    """Checkbox widget for forms"""
+    
+    def __init__(self, *, field: Optional['Field'] = None, label: str = "", **kwargs):
+        kwargs.setdefault('id', next(_id_gen))
+        super().__init__(value=False, **kwargs)
+        self.field = field
+        if label:
+            self.label = label
+    
+    def validate(self, value):
+        """Validate checkbox value"""
+        return ValidationResult()
+
+
+class AlwaysValid(Validator):
+    """Validator that always passes"""
+    
+    def validate(self, value):
+        return self.success()
+
+
+class FormSelect(Select):
+    """Select dropdown widget for forms"""
+    
+    def __init__(self, *, field: Optional['Field'] = None, 
+                 choices: List[Tuple[str, str]], allow_blank: bool = False,
+                 prompt: str = "Select an option", **kwargs):
+        kwargs.setdefault('id', next(_id_gen))
+        kwargs.setdefault('prompt', prompt)
+        
+        # Convert tuples to Select.Option objects
+        options = [(label, value) for value, label in choices]
+        
+        super().__init__(options=options, **kwargs)
+        self.field = field
+        self.allow_blank = allow_blank
+    
+    def validate(self, value):
+        """Validate select value"""
+        if value != Select.BLANK or self.allow_blank:
+            return AlwaysValid().success()
+        return AlwaysValid().failure("Please select a value")
+
+
+class WidgetRegistry:
+    """Registry for custom widgets"""
+    
+    _widgets = {}
+    
+    @classmethod
+    def register(cls, name: str):
+        """Decorator to register a widget"""
+        def decorator(widget_class):
+            cls._widgets[name] = widget_class
+            return widget_class
+        return decorator
+    
+    @classmethod
+    def get(cls, name: str):
+        """Get a widget by name"""
+        return cls._widgets.get(name)
+    
+    @classmethod
+    def list_widgets(cls):
+        """List all registered widgets"""
+        return list(cls._widgets.keys())
+
+
+# Register built-in widgets
+WidgetRegistry.register("input")(FormInput)
+WidgetRegistry.register("integer_input")(FormIntegerInput)
+WidgetRegistry.register("textarea")(FormTextArea)
+WidgetRegistry.register("checkbox")(FormCheckbox)
+WidgetRegistry.register("select")(FormSelect)

textual_wtf-0.8.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: textual-wtf
+Version: 0.8.0
+Summary: A declarative forms library for Textual TUI applications
+Author-email: Steve Holden <steve@holdenweb.com>
+License: MIT
+License-File: LICENSE
+Keywords: forms,terminal,textual,tui,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <4.0,>=3.10
+Requires-Dist: textual>=0.47.0
+Description-Content-Type: text/markdown
+
+# Textual Forms
+
+A declarative, extensible forms library for [Textual](https://textual.textualize.io/) TUI applications.
+
+## Features/Goals
+
+- **Declarative Syntax**: Define forms using class-based field declarations
+- **Flexible Widget Assignment**: Use different widgets for the same field type
+- **Easy to Extend**: Add custom field types and widgets with clear patterns
+- **Built-in Validation**: Uses standard textual validators
+- **Simple Integration**: Drop forms into existing Textual apps with minimal code
+
+
+## Warnings
+
+This package is in a beta stage. No details should be regarded as final,
+particularly naming details, but existing functionality won't be broken
+without a good reason. Nevertheless we believe it is sufficiently close to
+its final form to be rigorously exercised.
+
+Form layout is at present embedded in the Form.render method, which returns a
+RenderedForm widget making it difficult to provide flexibility in
+representation. This mechanism has extremely low "textuality," and will be
+replaced in release 0.9.
+
+LLMs have been used in the development of this package, which is
+subjected to serious scrutiny by a seasoned professional programmer, but this
+is no guarantee of quality or correctness. _caveat usor_.
+
+Some of the current tests are of dubious value, and may ultimately be removed.
+
+## Running the Examples
+
+If you have `uv` installed you can run the examples from the repository using the command
+
+`uvx --from git+https://github.com/holdenweb/textual-wtf.git textual-wtf`
+
+You will see a menu of demonstration examples, each of which is also a standalone program in the src/textual_wtf/demo directory.
+as shown below.
+
+|  Menu item                   | Program name           | Description                                  |
+|:-----------------------------|:-----------------------|:---------------------------------------------|
+| 1. Basic Form                | `basic_form.py`        | A simple form with basic fields              |
+| 2. Advanced Form             | `advanced_form.py`     | A more complex form with some validations    |
+| 3. User Registration         | `user_registration.py` | Rendered form integrated with other components        |
+| 4. Composition Example       | `nested_once_form.py`  | Simple nested form demonstration             |
+| 5. Multiply Included Example | `nested_twice_form.py` | Demonstrating form component re-use          |
+
+In a clone of the repository the command `uv run examples/<name>` should suffice.
+
+`poetry` users should find that they can create a virtual environment and run
+`poetry run textual-wtf` to start the demo. You can also build a distribution
+(wheel and sdist) of the project with `poetry build` and install that
+wherever required. No further testing in other development environments has
+so far been reported.
+
+## Installation
+
+The package will shortly be released to PyPI at version 0.8.
+Until then, install from this repository as follows.
+
+```bash
+python -m pip install textual_wtf@git+https://github.com/holdenweb/textual-wtf.git
+```
+
+`uv` users can use
+
+```bash
+uv add textual_wtf@git+https://github.com/holdenweb/textual-wtf.git
+```
+
+## Quick Start
+
+The most basic forms contain one or more fields. When a form is submitted a
+`Form.Submitted` event is posted, whose `form` attribute allows access to
+values using field names. Here's a simple example.
+
+```python
+from textual_wtf import Form, StringField, IntegerField, BooleanField
+
+class UserForm(Form):
+    """Simple user registration form"""
+    name = StringField(label="Name", required=True)
+    age = IntegerField(label="Age", min_value=0, max_value=130)
+    active = BooleanField(label="Active User")
+```
+
+With a little styling this is how the rendered form appears after it's been filled out.
+
+![The rendered form](images/rendered_user_form.png "Look!")
+
+Fields are named from the class variable to which they are assigned (in the
+example above, "name", "age" and "active"). With the content shown the
+form's `get_data` method will return `{'name': 'Steve Holden', 'age': 178;
+'active': True}`. Note that the integer field has been converted to an
+`int`, and the Boolean field to a `bool`.
+
+Forms are themselves reusable components so a form can contain sub-forms, as
+demonstrated in the `nested_once_form.py` example, to as many levels as
+required.
+
+A form can optionally be given a prefix, which is prepended to the names of
+its fields with a "_" suffix. This lets you include multiple instances of the
+same sub-form, as the `nested_twice_form.py` example demonstrates.
+
+In the event of two fields receiving the same (fully-qualified) name an
+exception is raised when the form is created.
+
+When a form is rendered "Cancel" and "Submit" buttons are added at the
+bottom of the form. When clicked these buttons raise `Form.Cancelled`
+and `Form.Submitted` events respectively; each has a `form` attribute
+which can be used to access the form.
+This behaviour will be more configurable in later releases.
+
+## Form Data
+
+Once rendered, the simplest way to access the form's data is
+by calling its `get_data` method.
+This returns a dictionary where fields' values are keyed by their
+fully-qualified names (i.e. including any sub-form prefixes,
+with underscores separating the named components).
+
+Users may find that in dealing with complex nested forms it
+becomes tedious to use fully-qualified names.
+An experimental `get_field` method takes a string argument. If that string is
+the fully-qualified name of a field, or if there is only one field whose
+fully-qualified name ends an underscore followed by the string, then it
+returns a field object whose attributes include `name` and `value`.
+
+This access mechanism is perhaps the most fluid part of the current design,
+and discussions (feel free to raise a Github issue to start a discussion -
+we'll move it into Discussions if it looks like developing) are encouraged.
+For example, would it more usable to implement a read/write property with
+dotted access? Should alternatives be offered?
+
+## Current Field Types
+
+- `StringField` - Text input (single line)
+- `TextField` - Text input (multi-line)
+- `IntegerField` - Integer input with validation
+- `BooleanField` - Checkbox
+- `ChoiceField` - Select dropdown
+
+Documentation of the foundational classes (Forms, Fields and Widgets) is the
+biggest current technical debt. The `examples` directory
+contains some code that we hope will help you to evalute textual-wtf
+and shape its direction with your feedback.
+
+Additional example programs, particularly those demonstrating the
+styling possibilities, would be especially valuable.
+
+## Development
+
+```bash
+# Create a venv with dev dependencies
+uv venv
+
+# Run tests
+uv run pytest
+
+ Run specific test
+uv run pytest tests/test_fields.py
+```
+
+## Architecture
+
+The library uses a three-layer architecture:
+
+1. **Fields** - Handle data conversion and validation logic
+2. **Widgets** - Handle UI rendering and user interaction
+3. **Forms** - Coordinate fields and widgets into complete forms
+
+No detailed architecture documentation is presently available.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Choice Field Format
+
+When using `ChoiceField`, provide choices as a list of `(value, label)` tuples:
+
+```python
+country = ChoiceField(
+    label="Country",
+    choices=[
+        ("us", "United States"),  # value, label
+        ("uk", "United Kingdom"),
+        ("ca", "Canada"),
+    ]
+)
+```
+
+- The **value** (first element) is what gets stored in the form data
+- The **label** (second element) is what the user sees in the dropdown
+
+When the form is submitted, `form.get_data()['country']` will contain the
+value (e.g., `"us"`), not the label.
+
+## Older versions
+
+The prehistory of the project is preserved in the `prototype` branch,
+a somewhat chaotic mishmash of code that nevertheless proved the basic ideas
+embodied in the current design to be usable in practice.

textual_wtf-0.8.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+textual_wtf/__init__.py,sha256=lo3oT72caUN0tiVmkVLY5JXGEisUwxA_xYPhgfdGzkQ,1345
+textual_wtf/bound_fields.py,sha256=Jk5o81dRlvuGivR_XdtjOo7_SE-J8HuEVdrJrZhimG8,8570
+textual_wtf/exceptions.py,sha256=GYef5rI0ygqXVHvBO5lrV_Ltu78FPkNvAyRSnFXe2vY,594
+textual_wtf/fields.py,sha256=gODdtGJySuBycCeiUKvvU2k1nLRAdPMvALsrqKz1oSA,8782
+textual_wtf/forms.py,sha256=tAXvf2p7OD2unBMbBA_uaOr2_6jzuMRzjVgfT_WlOco,14335
+textual_wtf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+textual_wtf/validators.py,sha256=635-JKuC9N0GAvy7No-mID_HtcvNvhKDBBI6FW4W0sQ,1192
+textual_wtf/version.py,sha256=iPlYCcIzuzW7T2HKDkmYlMkRI51dBLfNRxPPiWrfw9U,22
+textual_wtf/widgets.py,sha256=d5a0DiTJtdlQsQkeTvhEsHLDYwqEVn_zC6v8DzyN3NI,5130
+textual_wtf/demo/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+textual_wtf/demo/advanced_form.py,sha256=sK9aRE8fp3OtDiWf9c3qpIMKz4pIjCpy5SE5J6o7t0g,3604
+textual_wtf/demo/basic_form.py,sha256=x9RiosmkzDC0mYPdEMiGlRFqX0O9C5dJVyw1XdXdcpo,2655
+textual_wtf/demo/basic_form.tcss,sha256=bRKdPZyIC1mLjfkmQiwcc3JwzcSDWI3EeLs42JeneSw,71
+textual_wtf/demo/launcher.py,sha256=41DOguB7Dism9zav3NTBMJhtvkmi3bpfeocM3MvoPdk,3306
+textual_wtf/demo/nested_once_form.py,sha256=Ta_86TDYgwg8QOjVyVgaRMKjPHAC4b64AR9ymURLR3M,5036
+textual_wtf/demo/nested_twice_form.py,sha256=JDSDaO03p4p8tl562pNTnXXPN3Q5fDTqOvZ3dZ1L0SY,5063
+textual_wtf/demo/results_screen.py,sha256=3DsL-WRXA9x9AdpT6r3HD3-snlEk9kzy_XwB7O4FsqU,2035
+textual_wtf/demo/user_registration.py,sha256=LxyetdJmVs3G0ZoUr8PdGmFo-GEVPleCxdZZfEVAnJw,3540
+textual_wtf-0.8.0.dist-info/METADATA,sha256=-IQ6VDcCKUpsGHo4mTE-ahcHmGBQ-UcftPzuVUSi-bE,8578
+textual_wtf-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+textual_wtf-0.8.0.dist-info/entry_points.txt,sha256=jaJ4-T5M_61CTqJGCnRwAv6T7fVhWDzBaLKtTnoBbSM,63
+textual_wtf-0.8.0.dist-info/licenses/LICENSE,sha256=OD-OyOXFRBQ9lM4Z-XGnP_WUfVObajlPYdVVP3c_7OM,1089
+textual_wtf-0.8.0.dist-info/RECORD,,

textual_wtf-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

textual_wtf-0.8.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+textual-wtf = textual_wtf.demo.launcher:main

textual_wtf-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steve Holden steve@holdenweb.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.