StreamLens/TEXTUAL_API_CHECKLIST.md

Textual API Validation Checklist

Before Using Textual APIs

1. Event Names

• DataTable events:
  • ✅ RowHighlighted - When cursor moves to a row
  • ✅ RowSelected - When row is selected (Enter key)
  • ✅ CellHighlighted - When cursor moves to a cell
  • ✅ CellSelected - When cell is selected
  • ✅ ColumnHighlighted - When column is highlighted
  • ✅ HeaderSelected - When header is clicked
  • ❌ CursorMoved - Does NOT exist
  • ❌ SelectionChanged - Does NOT exist

2. DataTable Methods

• ✅ add_row() - Add a row with optional key
• ✅ clear() - Clear all rows
• ✅ move_cursor() - Move cursor programmatically
• ❌ set_row_style() - Does NOT exist (use CSS classes)
• ✅ add_column() - Add a column
• ✅ remove_row() - Remove a row by key

3. Common Attribute Patterns

• Properties: cursor_row, cursor_column, row_count, rows
• Events: Always check with dir(Widget) or test imports
• Messages: Custom messages need from textual.message import Message

4. Model Attributes Checklist

When adding UI that accesses model attributes:

• Check if attribute exists in model class
• Add missing attributes with appropriate defaults
• Consider if attribute should be calculated or stored
• Update any related initialization code

5. Testing Strategy

# Quick validation script
from textual.widgets import DataTable
print("Available events:", [attr for attr in dir(DataTable) if 'Selected' in attr or 'Highlighted' in attr])

6. Common Pitfalls

1. Event naming: Textual uses specific naming patterns
2. Method availability: Not all expected methods exist
3. CSS vs API: Some styling must be done via CSS
4. Message inheritance: Custom messages need proper base class

Validation Commands

# Check available attributes
source venv/bin/activate
python -c "from textual.widgets import DataTable; print(dir(DataTable))"

# Check specific event
python -c "from textual.widgets import DataTable; print('EventName' in dir(DataTable))"

# Check imports
python -c "from textual.widgets import WidgetName"

Model Validation

Before running the app, validate all model attributes are present:

# Run a quick attribute check
python -c "from analyzer.models.flow_stats import FlowStats, EnhancedAnalysisData; 
fs = FlowStats('', ''); 
print('Required attrs:', ['duration', 'first_seen', 'last_seen', 'jitter'])"