todo-cli-CrazyChief 0.1.0

A command-line TODO list application

TODO CLI Technical Documentation

Table of Contents

• User Guide
  • Installation
  • Configuration
  • Usage
    • Adding Tasks
    • Listing Tasks
    • Completing Tasks
    • Deleting Tasks
• Developer Guide
  • Architecture
  • Project Structure
  • Core Components
  • Extending the Application

User Guide

Installation

You can install the TODO CLI application using one of the following methods:

Method 1: Install from PyPI (Recommended for Users)

pip install todo-cli

Method 2: Install from Source (Recommended for Developers)

1. Clone the repository:

git clone <repository-url>
cd todo_cli

2. Create and activate a virtual environment:

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

3. Install in development mode:

pip install -e .

This will install all required dependencies and the CLI tool. The -e flag installs the package in "editable" mode, which is useful for development.

System Requirements

• Python 3.6 or higher
• pip package manager

Verifying Installation

After installation, verify that the CLI tool is available:

todo --help

You should see the help message with available commands.

Configuration

The TODO CLI application can be configured using environment variables:

• TODO_STORAGE_TYPE: Type of storage backend to use (default: 'json')
• TODO_STORAGE_PATH: Path to the storage file/directory (default: '~/.todo/tasks.json')

Example:

export TODO_STORAGE_PATH="/custom/path/tasks.json"

Usage

Adding Tasks

todo add "Complete documentation" -d "Write user and developer guides"

Listing Tasks

todo list

Completing Tasks

todo complete <task-id>

Deleting Tasks

todo delete <task-id>

Developer Guide

Architecture

The application follows a layered architecture pattern:

1. CLI Layer (cli.py)

   • Handles command-line interface and user interaction
   • Uses Click for command parsing
   • Formats output using Rich library

2. Service Layer (service.py)

   • Implements business logic
   • Manages task operations
   • Coordinates between CLI and storage

3. Storage Layer (storage.py)

   • Handles data persistence
   • Provides abstract interface for storage backends
   • Includes JSON file implementation

Project Structure

todo_cli/
├── todo_cli/
│   ├── __init__.py
│   ├── cli.py        # Command-line interface
│   ├── config.py     # Configuration management
│   ├── models.py     # Data models
│   ├── service.py    # Business logic
│   └── storage.py    # Storage implementations
├── requirements.txt
└── docs/
    └── README.md

Core Components

Models

The Task model (models.py) represents a todo item with the following attributes:

• id: Unique identifier
• title: Task title
• description: Optional task description
• status: Task status (OPEN/COMPLETED)
• created_at: Creation timestamp
• completed_at: Completion timestamp

Storage System

The storage system is designed to be extensible:

1. Abstract Base Class (Storage):

class Storage(ABC):
    @abstractmethod
    def add_task(self, task: Task) -> None: pass
    @abstractmethod
    def get_task(self, task_id: str) -> Optional[Task]: pass
    @abstractmethod
    def list_tasks(self) -> List[Task]: pass
    @abstractmethod
    def update_task(self, task: Task) -> None: pass
    @abstractmethod
    def delete_task(self, task_id: str) -> None: pass

2. JSON File Implementation (JsonFileStorage):

• Stores tasks in a JSON file
• Handles file creation and data serialization
• Thread-safe file operations

Extending the Application

Adding a New Storage Backend

1. Create a new class implementing the Storage interface:

from todo_cli.storage import Storage

class MyCustomStorage(Storage):
    def __init__(self, connection_string: str):
        # Initialize your storage
        pass

    def add_task(self, task: Task) -> None:
        # Implement task creation
        pass

    # Implement other required methods

2. Register the backend in config.py:

from todo_cli.config import StorageConfig
StorageConfig.register_backend("custom", MyCustomStorage)

Adding New Commands

1. Add a new command in cli.py:

@cli.command()
@click.argument("arg_name")
@click.option("--option-name", help="Option description")
def new_command(arg_name: str, option_name: str):
    """Command description."""
    service = get_service()
    # Implement command logic

2. Add corresponding service method in service.py:

def new_service_method(self, param: str) -> Result:
    # Implement service logic
    pass

Error Handling

The application uses standard Python exceptions for error handling:

• KeyError: For not found errors
• ValueError: For validation errors
• Custom exceptions can be added for specific cases

Testing

To run tests:

python -m pytest tests/

When adding new features:

1. Write unit tests for new components
2. Ensure existing tests pass
3. Update documentation as needed

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement changes with tests
4. Submit a pull request

Please follow the existing code style and include appropriate documentation updates.