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, 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.

Installation

Install from PyPI:

pip install hotkoffee

For desktop mode support:

pip install hotkoffee[desktop]

Installing from source (development)

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

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

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:

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)

Desktop mode

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

hk.run(desktop=True)

More runnable examples are available in the examples/ directory, including a CSV editor, an MQTT dashboard, and a theme builder demo.

Toasts and notifications

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:

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

hk.run() parameters

Testing

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

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, etc.)
├── layout/          # Layout containers (row, column, grid, card, break)
├── data/            # CSV read/write utilities
├── renderers/       # Web (FastAPI/WebSocket) and desktop rendering backends
└── theme_builder.py  # Theme/config helpers

examples/            # Runnable example apps
tests/               # Test suite

License

This project is licensed under the MIT License.

Contributing

Contributions, issues, and feature requests are welcome. Feel free to open an issue or submit a pull request on GitHub.

Author

Jiyo P V