Metadata-Version: 2.4
Name: hotkoffee
Version: 0.1.9
Summary: A lightweight, reactive UI framework for building Python-based web dashboards and applications.
Author-email: Jiyo P V <jiyopv21@gmail.com>
License: MIT License
        
        Copyright (c) 2026 hotkoffee
        
        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/Jiyo-pv/hotkoffee
Project-URL: Repository, https://github.com/Jiyo-pv/hotkoffee
Project-URL: Issues, https://github.com/Jiyo-pv/hotkoffee/issues
Keywords: web,framework,dashboard,reactive,ui,fastapi
Classifier: Development Status :: 3 - Alpha
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 :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.95.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: websockets>=11.0
Requires-Dist: paho-mqtt>=1.6.1
Requires-Dist: pandas>=2.0.0
Provides-Extra: desktop
Requires-Dist: pywebview>=4.0.0; extra == "desktop"
Requires-Dist: qtpy>=2.4.0; extra == "desktop"
Requires-Dist: PyQt6>=6.5.0; extra == "desktop"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# hotkoffee

[![PyPI version](https://img.shields.io/pypi/v/hotkoffee.svg)](https://pypi.org/project/hotkoffee/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python versions](https://img.shields.io/pypi/pyversions/hotkoffee.svg)](https://pypi.org/project/hotkoffee/)

hotkoffee is a lightweight, reactive UI framework for building Python-based web dashboards and applications. It offers a streamlined development experience by allowing developers to construct fully interactive interfaces using pure Python, eliminating the need for a separate frontend layer.

Under the hood, hotkoffee is powered by FastAPI and WebSockets, giving you real-time, reactive updates between your Python state and the rendered UI — in the browser or as a native desktop window.

---

## Features

- **Reactive state** — `hk.state()` wraps any value; updating `.value` automatically re-renders everything bound to it.
- **Widgets** — text, title, button, input, image, chart, table, metric, status, print button, toast, and notifications.
- **Layouts** — `column`, `row`, `grid`, and `card` containers for structuring your UI.
- **Auto-schema tables** — tables can start with zero columns and automatically detect and extend their schema as new fields stream in.
- **CSV support** — read and save CSV data directly with `read_csv` / `save_csv`.
- **MQTT integration** — build live, streaming dashboards fed by MQTT data sources.
- **Background workers** — run long-lived or polling tasks with `run_background` without blocking the UI.
- **Theming** — customize colors and border radius via `set_config`.
- **Desktop mode** — run the same app as a native desktop window using `pywebview`, no browser required.
- **Ready-made examples** — includes live weather, MQTT telemetry, CSV editing, and theme builder demos.

---

## Installation

Install from PyPI:

```bash
pip install hotkoffee
```

For desktop mode support:

```bash
pip install hotkoffee[desktop]
```

### Installing from source (development)

```bash
git clone https://github.com/Jiyo-pv/hotkoffee.git
cd hotkoffee
pip install -r requirements.txt
```

### Requirements

- Python 3.8+
- fastapi >= 0.95.0
- uvicorn >= 0.20.0
- websockets >= 11.0
- paho-mqtt >= 1.6.1
- pandas >= 2.0.0
- pywebview >= 4.0.0 (only required for desktop mode)
- pytest >= 8.0.0 (for running tests)

---

## Quickstart

```python
import hotkoffee as hk

count = hk.state(0)
hk.text("Count:", count)
hk.button("Increment +1", on_click=lambda: setattr(count, 'value', count.value + 1))
hk.run()
```

Run the script and hotkoffee will start a local server and open your default browser automatically:

```
[hotkoffee] Running at http://127.0.0.1:8000
```

---

## Usage Examples

### Layouts and reactive input

```python
import hotkoffee as hk

count = hk.state(0)
username = hk.state("Developer")

def inc():
    count.value += 1

with hk.card():
    hk.text("hotkoffee Application")
    hk.text("User Profile: <b>", username, "</b>")
    hk.input(username, placeholder="Type your name...")
    hk.break_()
    hk.text("Reactive Click Count: <b>", count, "</b>")
    hk.button("Click to Increment", on_click=inc)

hk.run()
```

### Auto-detecting live tables

Tables can start empty and automatically extend their schema as new fields appear in streamed data — useful for sensor feeds, telemetry, or any evolving JSON payload:

```python
import hotkoffee as hk

with hk.card():
    hk.text("Live Sensor Table")
    tbl = hk.table(max_rows=10, editable=True)

def sensor_worker():
    tbl.append({"timestamp": "10:00:01", "temp": 22.4, "humidity": 45.0})
    tbl.append({"timestamp": "10:00:02", "temp": 23.1, "humidity": 44.2, "pressure": 1013.2})

hk.run_background(sensor_worker)
hk.run(open_browser=False)
```

### Live weather dashboard

A more advanced example is included in the project: a fully built weather-monitoring dashboard with reactive metrics, status cards, charts, live data simulation, notifications, image content, and exportable tables.

```bash
py examples/live_weather_dashboard.py
```

### Desktop mode

Run the exact same app as a native desktop window instead of a browser tab:

```python
hk.run(desktop=True)
```

More runnable examples are available in the [`examples/`](./examples) directory, including a live weather dashboard, CSV editor, MQTT dashboard, and theme builder demo.

---
### Toasts and notifications

```python
import hotkoffee as hk

with hk.row():
    hk.title("Dashboard")
    bell = hk.notifications()

def on_save():
    hk.toast("Saved!", type="success")
    bell.add("File saved", level="success")

hk.button("Save", on_click=on_save)
hk.run()
```
## Theming

hotkoffee supports simple string-based theme configuration:

```python
hk.set_config("table:#141417,text:#d7d7e5,chart:#b5bdc9,button:#3b82f6,input:#3b82f6,body:#1cb54a,radius:rounded")
```

Configurable keys include `table`, `text`, `chart`, `button`, `input`, and `body` colors (as hex values), plus layout options like `radius`.

---

## API Overview

| Function / Class | Description |
|---|---|
| `hk.state(value)` | Creates a reactive `State` object |
| `hk.text(...)` | Renders text, optionally bound to reactive state |
| `hk.title(...)` | Renders a title element |
| `hk.button(label, on_click=...)` | Renders a clickable button |
| `hk.input(state, placeholder=...)` | Renders a text input bound to state |
| `hk.image(...)` | Renders an image |
| `hk.chart(...)` | Renders a chart |
| `hk.metric(title, value)` | Renders a metric summary card for key values |
| `hk.status(title, value)` | Renders a live status card based on a boolean-like value |
| `hk.table(...)` | Renders a data table with optional auto-schema and editing |
| `hk.print_button(...)` | Renders a button that triggers printing |
| `hk.toast(message, type=..., duration=...)` | Shows a transient toast notification (`info`/`success`/`warning`/`error`) |
| `hk.notifications()` | Renders a bell icon with an unread badge and dropdown panel; call `.add(message, level=...)` to push entries |
| `hk.column()` / `hk.row()` / `hk.grid()` / `hk.card()` | Layout containers (use as context managers) |
| `hk.break_()` | Inserts a line break in the layout |
| `hk.read_csv(...)` / `hk.save_csv(...)` | Read/write CSV data |
| `hk.run_background(fn)` | Runs a function in a background thread |
| `hk.set_config(...)` | Applies theme/config settings |
| `hk.run(...)` | Starts the hotkoffee server |

### `hk.run()` parameters

| Parameter | Default | Description |
|---|---|---|
| `host` | `"127.0.0.1"` | Interface to bind to. Use `"0.0.0.0"` to expose on the local network. |
| `port` | auto (starting at 8000) | Port to bind. If occupied, the next free port up to 8010 is selected automatically. |
| `desktop` | `False` | Launches a native desktop window via `pywebview` instead of a browser tab. |
| `reload` | `False` | Enables hot-reload for development. |
| `open_browser` | `True` | Automatically opens the default browser on startup. Set `False` for headless/server use. |

---

## Testing

hotkoffee ships with a test suite covering core functionality, widgets, and examples. Clone the repo and run:

```bash
git clone https://github.com/Jiyo-pv/hotkoffee.git
cd hotkoffee
pip install -r requirements.txt
pytest
```

---

## Project Structure

```
hotkoffee/
├── core/             # State management, config, background tasks, app/component core
├── widgets/          # UI widgets (text, button, input, chart, table, metric, status, etc.)
├── layout/           # Layout containers (row, column, grid, card, break)
├── data/             # CSV read/write utilities
├── renderers/        # Web (FastAPI/WebSocket) and desktop rendering backends
├── __init__.py       # Public package exports
├── theme_builder.py  # Theme/config helpers
└── ...

examples/            # Runnable example apps including live weather, MQTT, CSV editor
tests/               # Test suite
```

---

## License

This project is licensed under the [MIT License](./LICENSE).

## Contributing

Contributions, issues, and feature requests are welcome. Feel free to open an issue or submit a pull request on [GitHub](https://github.com/Jiyo-pv/hotkoffee).

## Author

**Jiyo P V**
