diff --git a/pomodoro-timer/README.md b/pomodoro-timer/README.md new file mode 100644 index 00000000..b84134bf --- /dev/null +++ b/pomodoro-timer/README.md @@ -0,0 +1,47 @@ +# Pomodoro Timer + +A CLI-based productivity tool that implements the Pomodoro Technique for effective time management. + +## What is the Pomodoro Technique? + +The Pomodoro Technique is a time management method developed by Francesco Cirillo in the late 1980s. It uses a timer to break work into intervals, traditionally 25 minutes in length, separated by short breaks. Each interval is known as a pomodoro, from the Italian word for tomato, after the tomato-shaped kitchen timer Cirillo used as a university student. + +## How It Works + +1. Choose a task to work on +2. Set the timer for 25 minutes (one pomodoro) +3. Work on the task until the timer rings +4. Take a short 5-minute break +5. After every 4 pomodoros, take a longer 15-minute break +6. Repeat the cycle + +## Features + +- Configurable work and break durations +- Automatic session counting +- Long break after every 4 work sessions +- Clean CLI display with countdown timer +- Graceful exit with session summary on Ctrl+C + +## Usage + +Run the timer with default settings (25 min work, 5 min short break, 15 min long break): + +```bash +python pomodoro_timer.py +``` + +Customize the durations: + +```bash +python pomodoro_timer.py --work 30 --short-break 10 --long-break 20 +``` + +## Requirements + +- Python 3.6 or higher +- No external dependencies (uses only standard library modules) + +## Implementation Details + +This implementation uses Python's built-in `argparse` module for command-line argument parsing, `time.sleep()` for the countdown mechanism, and carriage return (`\r`) for inline timer display updates. The timer runs in an infinite loop until interrupted by the user with Ctrl+C, at which point it displays a summary of completed sessions. diff --git a/pomodoro-timer/pomodoro_timer.py b/pomodoro-timer/pomodoro_timer.py new file mode 100644 index 00000000..bb40cda6 --- /dev/null +++ b/pomodoro-timer/pomodoro_timer.py @@ -0,0 +1,109 @@ +""" +Pomodoro Timer - A CLI productivity tool + +Implements the Pomodoro Technique: 25-minute work sessions followed by +5-minute short breaks, with a 15-minute long break after every 4 sessions. + +Usage: + python pomodoro_timer.py [--work MINUTES] [--short-break MINUTES] [--long-break MINUTES] + +Example: + python pomodoro_timer.py --work 25 --short-break 5 --long-break 15 +""" + +import argparse +import sys +import time + + +def display_timer(seconds: int, session_type: str) -> None: + """Display a countdown timer with session type label. + + Args: + seconds: Remaining time in seconds. + session_type: Label for the current session (e.g., 'Work', 'Short Break'). + """ + minutes = seconds // 60 + secs = seconds % 60 + print(f"\r {session_type}: {minutes:02d}:{secs:02d} ", end="", flush=True) + + +def countdown(duration_minutes: int, session_type: str) -> None: + """Run a countdown timer for the specified duration. + + Args: + duration_minutes: Length of the timer in minutes. + session_type: Label displayed during the countdown. + """ + total_seconds = duration_minutes * 60 + for remaining in range(total_seconds, -1, -1): + display_timer(remaining, session_type) + time.sleep(1) + print() # New line after timer completes + + +def run_pomodoro(work_min: int, short_break_min: int, long_break_min: int) -> None: + """Execute the full Pomodoro Technique cycle. + + Runs 4 work sessions with short breaks in between, followed by a long break. + After the long break, the cycle repeats indefinitely until interrupted. + + Args: + work_min: Duration of each work session in minutes. + short_break_min: Duration of short breaks in minutes. + long_break_min: Duration of the long break in minutes. + """ + session_count = 0 + + print("=" * 50) + print(" POMODORO TIMER") + print(" Press Ctrl+C to stop at any time") + print("=" * 50) + + try: + while True: + session_count += 1 + print(f"\n>>> Session {session_count} starting...") + + countdown(work_min, "Work") + print(" Work session complete! Time for a break.") + + if session_count % 4 == 0: + print(f" Great job! Taking a long break ({long_break_min} min).") + countdown(long_break_min, "Long Break") + else: + print(f" Taking a short break ({short_break_min} min).") + countdown(short_break_min, "Short Break") + + print(" Break over. Ready for the next session!") + + except KeyboardInterrupt: + print(f"\n\nTimer stopped. Completed {session_count} session(s).") + print("Stay productive!") + sys.exit(0) + + +def parse_arguments() -> argparse.Namespace: + """Parse command-line arguments for timer configuration. + + Returns: + Parsed arguments namespace with work, short_break, and long_break values. + """ + parser = argparse.ArgumentParser( + description="Pomodoro Timer - Boost your productivity with timed work sessions" + ) + parser.add_argument( + "--work", type=int, default=25, help="Work session duration in minutes (default: 25)" + ) + parser.add_argument( + "--short-break", type=int, default=5, help="Short break duration in minutes (default: 5)" + ) + parser.add_argument( + "--long-break", type=int, default=15, help="Long break duration in minutes (default: 15)" + ) + return parser.parse_args() + + +if __name__ == "__main__": + args = parse_arguments() + run_pomodoro(args.work, args.short_break, args.long_break)