This document tracks the development milestones for the ThothSpinner project, a collection of custom spinner components for Python terminal applications with Rich and Textual support.
Legend:
[x]Completed[-]In Progress[ ]Not Started
Goal/Requirement: Set up the ThothSpinner Python project and implement the Hint component
- Initialize modern Python project structure with UV
- Configure development toolchain (ruff, ty, just)
- Implement and test the Hint component for Rich
Out of Scope:
- Textual component implementation
- Other components (Spinner, Progress, Timer, Message)
- Complex animations or state management
See M01.md for detailed task list
from thothspinner.rich.components import HintComponent
from rich.console import Console
console = Console()
hint = HintComponent(text="Press ESC to cancel", color="#FF5555")
console.print(hint)make check- Verifies environment dependenciesjust test- All tests pass (90%+ coverage)
- Visual verification of Hint component rendering
- Terminal compatibility testing
Goal/Requirement: Implement the animated Spinner component
- Create frame-based animation system
- Support multiple spinner styles (NPM dots, Claude stars, custom)
- Add state transformation capabilities
See M02.md for detailed task list
from thothspinner.rich.components import SpinnerComponent
from rich.console import Console
from rich.live import Live
import time
console = Console()
spinner = SpinnerComponent(style="npm_dots", color="#D97706")
with Live(spinner, console=console, refresh_per_second=20):
# Perform long-running operation
time.sleep(5)
spinner.success()make check- Verifies environment dependenciesjust test- All tests pass (90%+ coverage)
- Visual verification of spinner animations
- State transition testing (in_progress → success/error)
- Performance monitoring (CPU < 5%, smooth 20 FPS)
Goal/Requirement: Implement Progress counter and Timer components
- Create Progress component with multiple display formats
- Implement Timer with various time formats
- Add update methods and state management
See M03.md for detailed task list
from thothspinner.rich.components import ProgressComponent, TimerComponent
from rich.console import Console
from rich.live import Live
import time
console = Console()
# Progress component with percentage
progress = ProgressComponent(
current=0,
total=100,
format={"style": "percentage"},
color="#55FF55"
)
# Timer component with auto format
timer = TimerComponent(
format={"style": "auto", "precision": 1},
color="#FFFF55"
)
# Combined display
with Live([progress, timer], console=console, refresh_per_second=10):
timer.start()
for i in range(101):
progress.set(i)
time.sleep(0.1)
timer.stop()
progress.success()make check- Verifies environment dependenciesjust test- All tests pass (97%+ coverage achieved)just lint- No linting errorsjust typecheck- No type errors
- Visual verification of Progress component formats
- Timer format transitions at time boundaries
- State change behavior (success/error)
- Terminal compatibility testing
- Performance monitoring (CPU < 1%, memory stable)
Goal/Requirement: Implement the Message component with shimmer effects
- Create action words rotation system
- Implement shimmer animation effect
- Add directional control for shimmer
To be defined in M04.md
Goal/Requirement: Combine all components into unified ThothSpinner
- Create parent orchestrator component
- Implement state management system
- Add configuration hierarchy
To be defined in M05.md
Goal/Requirement: Document all Rich components and orchestrator
- Document all Rich components (Hint, Spinner, Progress, Timer, Message)
- Document Rich ThothSpinner orchestrator
- Create Rich-specific examples and usage guides
- API reference for Rich components
To be defined in M06.md
Goal/Requirement: Implement Textual Hint widget
- Implement Textual Hint widget
- Add reactive state management for Hint
- Ensure feature parity with Rich HintComponent
To be defined in M07.md
Goal/Requirement: Implement Textual Spinner widget with animations
- Implement Textual Spinner widget with animations
- Support all spinner styles from Rich version
- Add reactive state transitions
To be defined in M08.md
Goal/Requirement: Implement Textual Progress widget
- Implement Textual Progress widget
- Support all format styles from Rich version
- Add reactive updates and state management
To be defined in M09.md
Goal/Requirement: Implement Textual Timer widget
- Implement Textual Timer widget
- Support all time formats from Rich version
- Add start/stop/pause reactive controls
To be defined in M10.md
Goal/Requirement: Implement Textual Message widget with shimmer
- Implement Textual Message widget with shimmer
- Support action words rotation
- Add reactive shimmer effects
To be defined in M11.md
Goal/Requirement: Create Textual orchestrator widget
- Create Textual orchestrator widget
- Implement state management for all Textual components
- Add configuration hierarchy for Textual apps
To be defined in M12.md
Goal/Requirement: Document all Textual components
- Document all Textual components
- Create Textual-specific examples
- Integration guides for Textual apps
- API reference for Textual widgets
To be defined in M13.md
Goal/Requirement: Publish package to PyPI
- Finalize package metadata
- Set up GitHub Actions for CI/CD
- Publish to PyPI
- Create release notes and changelog
To be defined in M14.md
Goal/Requirement: Extend the Textual ProgressWidget with visual bar format and smooth animated transitions
- Add "bar" format style with configurable fill characters, width, and brackets
- Add smooth animated transitions when progress values change
- Maintain full backward compatibility with existing ProgressWidget API
Note: Deferred from M09 (tasks M09-T04 and M09-T09) to maintain strict Rich feature parity in the initial ProgressWidget release.
See M15.md for detailed task list