danial-todo 0.1.0

Professional in-memory Python console todo app with beautiful TUI

Todo Evolution 🚀

Professional in-memory Python console todo app with beautiful TUI

A modern, feature-rich task management application that combines the power of a command-line interface with an intuitive, arrow-key navigable TUI dashboard. Built with Python 3.13+ and designed for developers who love working in the terminal.

✨ Features

• Beautiful TUI: Large ASCII banner "TODO EVOLUTION", rich-formatted tables, distinct colors
• Arrow-Key Navigation: Intuitive menu system powered by questionary
• Dual Modes:
  • Interactive Mode: Dashboard with visual feedback (default - just run todo)
  • Command Mode: Direct CLI operations for power users (todo add "Task")
• 5 Core Operations: Add, List, Update, Delete, Mark Complete/Incomplete
• Pure Python Services: Reusable as a library without CLI dependencies
• In-Memory Storage: Fast, simple, no persistence overhead
• 90%+ Test Coverage: Comprehensive unit and integration tests
• Type-Safe: Full type hints with mypy validation
• Developer-Friendly: Clean API, excellent error messages

📦 Installation

From PyPI (coming soon)

pip install danial-todo

From Source

# Clone the repository
git clone https://github.com/daniyalaneeq/todo-evolution.git
cd todo-evolution

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

🚀 Quick Start

Interactive Mode (Default)

Simply run todo to launch the TUI dashboard:

todo

You'll see:

   _____ ___  ____   ___
  |_   _/ _ \|  _ \ / _ \
    | || | | | | | | | | |
    | || |_| | |_| | |_| |
    |_| \___/|____/ \___/
  _____     _____ _   _ _____ ___ ___  _   _
 | __\ \   / / _ \ | | | |_   _|_ _/ _ \| \ | |
 |  _|\ \ / / | | | | | |   | |  | | | | |  \| |
 | |___\ V /| |_| | |_| |   | |  | | |_| | |\  |
 |_____\_/  \___/|____/|_|   |_| |___\___/|_| \_|

What would you like to do?
❯ Add Task
  List Tasks
  Update Task
  Delete Task
  Mark Complete/Incomplete
  Exit

Navigation:

• ⬆️ Up Arrow: Move selection up
• ⬇️ Down Arrow: Move selection down
• Enter: Confirm selection
• Ctrl+C: Exit

Command Mode (Power Users)

Execute operations directly from the command line:

# Add tasks
todo add "Buy groceries"
todo add "Write documentation"
todo add "Deploy application"

# List all tasks
todo list
# Output:
# ┌────┬───────────────────┬────────┐
# │ ID │ Title             │ Status │
# ├────┼───────────────────┼────────┤
# │  1 │ Buy groceries     │   ✗    │
# │  2 │ Write documentation│  ✗    │
# │  3 │ Deploy application│   ✗    │
# └────┴───────────────────┴────────┘

# Update a task
todo update 1 "Buy organic groceries"

# Mark task complete
todo complete 1

# Mark task incomplete
todo incomplete 1

# Delete a task
todo delete 2

# Get help
todo --help

💻 Usage Examples

Interactive Mode Workflow

# Launch interactive mode
todo

# Follow the prompts:
# 1. Select "Add Task"
# 2. Enter: "Prepare presentation"
# 3. Select "List Tasks" to verify
# 4. Select "Mark Complete/Incomplete" and enter task ID
# 5. Select "Exit" when done

Command Mode Workflow

# Quick task management
todo add "Morning standup at 9am"
todo add "Code review PR #123"
todo add "Deploy staging environment"

# Check your tasks
todo list

# Complete tasks as you go
todo complete 1
todo complete 2

# Update task details
todo update 3 "Deploy staging and notify team"

# Clean up completed tasks
todo delete 1
todo delete 2

# Check final state
todo list

Library Usage (Programmatic API)

Use Todo Evolution as a Python library in your own applications:

from todo_evolution import TaskService, Task

# Initialize service
service = TaskService()

# Add tasks
task1 = service.add_task("Deploy app to production")
task2 = service.add_task("Run database migrations")
task3 = service.add_task("Update monitoring dashboards")

print(f"Created task {task1.id}: {task1.title}")

# List all tasks
all_tasks = service.get_all_tasks()
for task in all_tasks:
    status = "✓" if task.status else "✗"
    print(f"[{status}] {task.id}: {task.title}")

# Get specific task
task = service.get_by_id(1)
if task:
    print(f"Found: {task.title}")

# Update task
updated = service.update_task(1, "Deploy app to production (urgent)")
print(f"Updated: {updated.title}")

# Mark complete
completed = service.toggle_status(2)
print(f"Task {completed.id} is now: {'complete' if completed.status else 'incomplete'}")

# Delete task
deleted = service.delete_task(3)
print(f"Deletion successful: {deleted}")

# Final count
remaining = service.get_all_tasks()
print(f"Total tasks remaining: {len(remaining)}")

Output:

Created task 1: Deploy app to production
[✗] 1: Deploy app to production
[✗] 2: Run database migrations
[✗] 3: Update monitoring dashboards
Found: Deploy app to production
Updated: Deploy app to production (urgent)
Task 2 is now: complete
Deletion successful: True
Total tasks remaining: 2

📚 API Reference

TaskService

Core business logic service for task management.

Methods

__init__() -> None

Initialize a new TaskService with empty state.

service = TaskService()

add_task(title: str) -> Task

Create a new task with auto-assigned ID.

Parameters:

• title (str): Task description (non-empty)

Returns: Task object with id, title, and status=False

Raises: ValueError if title is empty

task = service.add_task("Buy milk")
assert task.id == 1
assert task.status == False

get_all_tasks() -> list[Task]

Retrieve all tasks in creation order.

Returns: List of Task objects (may be empty)

tasks = service.get_all_tasks()
for task in tasks:
    print(task.title)

get_by_id(task_id: int) -> Task | None

Retrieve a specific task by ID.

Parameters:

• task_id (int): Task identifier

Returns: Task if found, None otherwise

task = service.get_by_id(1)
if task:
    print(task.title)

update_task(task_id: int, new_title: str) -> Task

Update the title of an existing task.

Parameters:

• task_id (int): Task identifier
• new_title (str): New description (non-empty)

Returns: Updated Task object

Raises: ValueError if task not found or title is empty

task = service.update_task(1, "Buy organic milk")

delete_task(task_id: int) -> bool

Remove a task from the collection.

Parameters:

• task_id (int): Task identifier

Returns: True if deleted, False if not found

success = service.delete_task(1)

toggle_status(task_id: int) -> Task

Toggle task completion status (complete ↔ incomplete).

Parameters:

• task_id (int): Task identifier

Returns: Updated Task object with toggled status

Raises: ValueError if task not found

task = service.toggle_status(1)
print("Complete" if task.status else "Incomplete")

Task

Data model representing a todo item.

Attributes

• id (int): Unique auto-incrementing identifier
• title (str): Task description (1-500 characters)
• status (bool): Completion state (False=incomplete, True=complete)

from todo_evolution.models import Task

task = Task(id=1, title="Example task", status=False)
print(f"{task.id}: {task.title} - {task.status}")

🧪 Development

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/todo-evolution.git
cd todo-evolution

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/todo_evolution --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_task_service.py -v

# Run integration tests only
pytest tests/integration/ -v

Code Quality

# Format code with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

# Type check with mypy
mypy src/

# Run all quality checks
black src/ tests/ && ruff check src/ tests/ && mypy src/ && pytest

Project Structure

src/todo_evolution/
├── __init__.py              # Package exports (Task, TaskService)
├── models/
│   ├── __init__.py
│   └── task.py              # Task dataclass
├── services/
│   ├── __init__.py
│   └── task_service.py      # CRUD operations
└── cli/
    ├── __init__.py
    ├── utils.py             # Banner, formatting utilities
    ├── interactive.py       # Interactive TUI mode
    ├── commands.py          # Command-line mode
    └── main.py              # Entry point router

tests/
├── conftest.py              # Shared pytest fixtures
├── unit/
│   ├── test_task_model.py      # Task model tests (6 tests)
│   └── test_task_service.py    # TaskService tests (27 tests)
└── integration/
    ├── test_interactive_cli.py # Interactive mode tests (20+ tests)
    └── test_command_cli.py     # Command mode tests (30+ tests)

📋 Requirements

• Python: 3.13 or higher
• Dependencies:
  • rich>=13.0.0 - Terminal formatting and tables
  • questionary>=2.0.0 - Interactive prompts
  • pyfiglet>=1.0.0 - ASCII art banner
• Development Dependencies:
  • pytest>=8.0.0 - Testing framework
  • pytest-cov>=4.0.0 - Coverage reporting
  • black>=24.0.0 - Code formatting
  • ruff>=0.1.0 - Fast linter
  • mypy>=1.8.0 - Type checking

🎯 Design Principles

• Separation of Concerns: Services layer is pure Python, CLI layer handles presentation
• Test-Driven Development: 90%+ test coverage with comprehensive unit and integration tests
• Type Safety: Full type hints for better IDE support and error detection
• User Experience: Beautiful, intuitive interface with clear error messages
• Library Reusability: Core logic usable without CLI dependencies

📖 Documentation

• Feature Specification - Requirements and user stories
• Implementation Plan - Technical architecture
• Data Model - Entity specifications
• API Contracts - Service and CLI interfaces
• Task List - Implementation task breakdown
• Quickstart Guide - Developer onboarding

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Run quality checks: black . && ruff check . && mypy src/ && pytest
5. Commit your changes: git commit -m 'feat: add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Commit Message Format

Follow Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• test: - Test updates
• refactor: - Code refactoring
• chore: - Maintenance tasks

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Rich for beautiful terminal output
• Interactive prompts powered by Questionary
• ASCII art by PyFiglet
• Inspired by modern CLI tools like GitHub CLI and Vercel CLI

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation

🗺️ Roadmap

Future enhancements (not in v1.0):

• Persistent storage (JSON, SQLite)
• Task categories and tags
• Due dates and reminders
• Priority levels
• Sub-tasks and dependencies
• Export/import functionality
• Multi-user support
• Web API

📊 Project Stats

• Lines of Code: ~1,500 (src + tests)
• Test Coverage: 90%+
• Test Count: 60+ comprehensive tests
• Type Safety: 100% type-hinted
• Documentation: Comprehensive specs and guides

---

Made with ❤️ by developers, for developers

Todo Evolution - Where productivity meets elegance in the terminal