Metadata-Version: 2.4
Name: caffeinate-me
Version: 0.2.0
Summary: A whimsical caffeine companion for coffee-loving developers
License: MIT License
        
        Copyright (c) 2024 Brett Buskirk
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/brett-buskirk/caffeinate-me
Project-URL: Repository, https://github.com/brett-buskirk/caffeinate-me
Project-URL: Issues, https://github.com/brett-buskirk/caffeinate-me/issues
Keywords: coffee,cli,fun,caffeine,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Caffeinate Me ☕

> A whimsical caffeine companion for coffee-loving developers.


`caffeinate-me` started as a single-function script and has grown into a full CLI tool with a rich quote library, coffee-type info, a local consumption tracker, brewing timers, and achievements.

---

## Installation

The recommended way to install `caffeinate-me` is with [pipx](https://pipx.pypa.io), which installs the CLI into an isolated environment and puts it permanently on your `PATH` — no virtual environment to activate, works in any terminal.

**Install pipx** (if you don't have it):

```bash
# macOS
brew install pipx

# Linux / WSL
sudo apt install pipx

# or via pip
pip install --user pipx
```

**Install caffeinate-me from PyPI:**

```bash
pipx install caffeinate-me
```

**Or install from source:**

```bash
git clone https://github.com/brett-buskirk/caffeinate-me.git
cd caffeinate-me
pipx install .
```

That's it — `caffeinate-me` is now available everywhere. Dependencies like `rich` are installed automatically inside the isolated environment.

**Requires Python 3.9+.**

---

## Usage

### Default — show a random quote

```bash
caffeinate-me
```

```
╭────────────────────────── ☕ Caffeinate Me ──────────────────────────────╮
│                                                                           │
│   ) ) )                                                                   │
│  ( ( (                                                                    │
│  ......                                                                   │
│  |    |]                                                                  │
│  \    /                                                                   │
│   `---'                                                                   │
│                                                                           │
│   "Coffee is my rubber duck. Time for another cup!"                       │
│                                                                           │
│   Recommended: ☕ Pour Over  •  100mg caffeine  •  Strong intensity       │
╰───────────────────────────────────────────────────────────────────────────╯
```

---

### Mood-based quotes

```bash
caffeinate-me --mood energetic   # motivational / programmer quotes
caffeinate-me --mood sleepy      # sarcastic / dark-humor quotes
caffeinate-me --mood stressed    # programmer stress-relief quotes
caffeinate-me --mood zen         # wholesome / mindful quotes
```

### Coffee-type info + recommendation

```bash
caffeinate-me --type espresso     # show espresso details + a quote
caffeinate-me --type cold-brew    # show cold-brew details + a quote
```

Available types: `espresso`, `americano`, `latte`, `cappuccino`, `cold-brew`,
`pour-over`, `french-press`, `mocha`, `macchiato`, `flat-white`

### Intensity filter

```bash
caffeinate-me --intensity mild      # recommend a lighter coffee
caffeinate-me --intensity strong    # recommend a strong coffee
caffeinate-me --intensity espresso  # espresso-level strength
```

### Plain text (no emoji)

```bash
caffeinate-me --no-emoji
```

---

## Consumption Tracker

Log each coffee and build up your stats over time.

```bash
caffeinate-me --log                  # log a coffee alongside your quote
caffeinate-me --log --type espresso  # log a specific type
caffeinate-me --stats                # view stats and achievements
```

### Stats view

```
    ☕ Your Coffee Stats
┌───────────────┬──────────┐
│ Today         │ 3 cup(s) │
│ This Week     │ 14 cup(s)│
│ All Time      │ 42 cup(s)│
│ Daily Average │ 2.1      │
│ Favourite     │ Espresso │
└───────────────┴──────────┘

🏆 Achievements  (3/7)
☕  First Cup      — Logged your very first coffee!
🔥  Triple Shot    — Had 3 coffees in one day!
🌅  Early Bird     — Had coffee before 6 AM!
·   Night Owl      — Had coffee after 10 PM!
...
```

### Achievements

| Icon | Name           | How to unlock                           |
|------|----------------|-----------------------------------------|
| ☕   | First Cup      | Log your very first coffee              |
| 🔥   | Triple Shot    | 3+ coffees in one day                   |
| 🌅   | Early Bird     | Coffee before 6 AM                      |
| 🦉   | Night Owl      | Coffee after 10 PM                      |
| 🏆   | Week Warrior   | Coffee every day for 7 consecutive days |
| 💯   | Century Club   | 100 coffees total                       |
| 🎨   | Variety Seeker | Try 5 different coffee types            |

### Export your data

```bash
caffeinate-me --export json   # JSON format
caffeinate-me --export csv    # CSV format
```

Data is stored locally in `~/.caffeinate_me/tracker.json`.

---

## Brewing Timer

```bash
caffeinate-me timer french-press   # 4-minute countdown
caffeinate-me timer espresso       # 30-second countdown
caffeinate-me timer --list         # show all brew times
```

Cold brew (12+ hours) skips the live timer and prints a reminder instead.

---

## Python API

The core function is still available for use in your own code:

```python
from caffeinate_me import caffeinate_me

print(caffeinate_me())
# "sudo make me a coffee. Time for another cup!"

print(caffeinate_me(mood="zen"))
# "Coffee is a warm hug in a mug. Time for another cup!"

print(caffeinate_me(no_emoji=True))
# "Maybe just a nap instead?"
```

---

## Quote Library

115 quotes across 8 categories:

| Category     | Flavour                                   |
|--------------|-------------------------------------------|
| motivational | Uplifting, get-things-done energy         |
| sarcastic    | Dry wit and coffee snob energy            |
| programmer   | Developer-specific coffee struggles       |
| wholesome    | Warm and fuzzy coffee feelings            |
| dark_humor   | Because sometimes coffee isn't enough     |
| morning      | Dawn-patrol, first-cup vibes              |
| afternoon    | 3 PM slump survival                       |
| evening      | Night-owl, deadline-fuelled motivation    |

---

## Project Structure

```
src/caffeinate_me/
├── __init__.py      — package entry, re-exports caffeinate_me()
├── core.py          — caffeinate_me() function (backward-compatible)
├── quotes.py        — 130+ quote library with categories
├── coffee_types.py  — coffee type info and time-of-day recommendations
├── tracker.py       — local JSON consumption tracker + achievements
├── timer.py         — brewing countdown timer (rich live display)
├── art.py           — ASCII coffee cup art
└── cli.py           — CLI entry point (argparse + rich)

tests/
├── test_core.py
├── test_quotes.py
├── test_tracker.py
└── test_coffee_types.py
```

---

## Contributing

Pull requests are welcome! The easiest way to contribute is to add new coffee quotes.
See the categories in [src/caffeinate_me/quotes.py](src/caffeinate_me/quotes.py) and submit a PR.

Run the tests before submitting:

```bash
pytest
```

---

## License

MIT. See [LICENSE](LICENSE).

---

*Coffee responsibly. This tool is for entertainment purposes only.*
