Metadata-Version: 2.4
Name: PomoTerm
Version: 0.1.0
Summary: A simple, lightweight, cross-platform Pomodoro timer for the command line.
Author-email: Nahikari Vallejo <nahikarivallejo@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SasoriAka96/PomoTerm
Project-URL: Repository, https://github.com/SasoriAka96/PomoTerm.git
Keywords: pomodoro,timer,cli,terminal,productivity,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PomoTerm

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![OS](https://img.shields.io/badge/OS-Windows%20%7C%20macOS%20%7C%20Linux-brightgreen.svg)]()

A lightweight, cross-platform Pomodoro CLI timer written in Python. Simple, clean, and designed to run directly from your terminal.

```text
 _____                      _____                      
|  __ \                    |_   _|                     
| |__) |__  _ __ ___   ___   | | ___  _ __ _ __ ___    
|  ___/ _ \| '_ ` _ \ / _ \  | |/ _ \| '__| '_ ` _ \   
| |  | (_) | | | | | | (_) | | |  __/| |  | | | | | |  
|_|   \___/|_| |_| |_|\___/  \_/\___||_|  |_| |_| |_|
```

---

## Features

* Cross-Platform Audio Support: Automatic system detection to trigger native notification sounds on Windows (winsound), macOS (afplay), and Linux (paplay).
* Interactive CLI Progress Bar: Clean terminal UI with inline progress updates using standard I/O flushing.
* Custom Durations: Flexibility to pass custom timer durations via command-line arguments.
* Packaging Support: Configured with pyproject.toml so it can be installed locally as a global executable (pomodoro).

---

## Requirements

* Python 3.8+
* Standard Library only! No external heavy dependencies required.
* System-specific audio players (pre-installed by default on most OS):
  * Windows: Native winsound support.
  * macOS: Native afplay command-line utility.
  * Linux: paplay (pulseaudio) installed.

---

## Installation & Usage

### 1. Local Development Setup

Clone the repository and install the package in editable mode:

```bash
git clone https://github.com/SasoriAka96/PomoTerm.git
cd PomoTerm
pip install -e .
```

### 2. Running the Timer

Once installed, you can launch the Pomodoro timer directly from anywhere in your terminal:

```bash
# Run with a 5-minute timer
pomodoro --min 5
```

Alternatively, you can run the main script directly with Python:

```bash
python -m src.main --min 5
```

---

## Project Structure

```text
PomoTerm/
├── src/
│   ├── __init__.py
│   ├── logic.py      # System detection and audio playback handling
│   ├── ui.py         # Argument parsing and progress bar display
│   └── main.py       # Main entry point
├── pyproject.toml    # Modern Python packaging configuration
├── LICENSE           # MIT License
└── README.md         # Project documentation
```

---

## Roadmap & Pending Features

- [x] Initial CLI timer with progress bar
- [x] Multi-platform system detection (Windows, macOS, Linux)
- [x] Audio notifications on completion
- [ ] Add full Pomodoro cycles (Work / Short Break / Long Break)
- [ ] Add sound configuration options (mute mode / custom alert tones)
- [ ] Desktop native popup notifications (using plyer or desktop notifications)
- [ ] PyPI package publication

---

## Author

Nahikari Vallejo

* GitHub: https://github.com/SasoriAka96
* Email: nahikarivallejo@gmail.com

---

## License

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