TaskTracker

TaskTracker is a minimal Python library for running tasks in parallel with a live terminal UI. Add it to any script in 2 lines — no decorators, no broker, no framework.

---

✨ Features

• 2-line integration — wrap any function, pass a task list, done
• Per-worker live status — see what each thread is doing in real time
• Built-in task queue — no manual Queue wiring
• Detailed file logging — DEBUG-level log, terminal stays clean
• Rich-powered UI — live progress, elapsed time, task names and descriptions
• Summary report — start/end times, per-worker stats, total duration

---

🆚 How It Compares

Library	Per-worker live UI	Task queue included	Integration	Threading
TaskTracker	✅	✅	2 lines	✅
tqdm	⚠ Manual wiring	❌	1 line (iterable)	✅
Rich Progress	⚠ ~15 lines setup	❌	Manual	✅
mpire	❌ Overall only	✅	3 lines	Process-based
atpbar	⚠ Iterable-only	❌	1 line	✅
RQ / Celery	❌	✅	Requires Redis/broker	❌

The gap TaskTracker fills: no other library combines per-worker live status, a built-in task queue, and sub-3-line integration in a single threading-native package.

---

📸 Screenshots

---

📦 Installation

Clone & install in editable mode:

git clone https://github.com/sungurerdim/tasktracker.git
cd tasktracker
pip install -e .

Install directly from GitHub:

pip install git+https://github.com/sungurerdim/tasktracker.git

🚀 Quick Start

from tasktracker import run, Task
import time, random

def my_action(file_path):
    time.sleep(random.uniform(2.0, 5.0))
    return True

if __name__ == "__main__":
    tasks = [
        Task(data="input/file_a.txt", name="File A", desc="Convert A to X"),
        Task("input/file_b.txt"),
        Task("input/file_c.txt", "File C", "Convert C to Z"),
    ]

    run(title="Demo Process", action=my_action, tasks=tasks, worker_count=2)

---

📁 Project Structure

.
├── tasktracker/
│   ├── __init__.py          # Public API: run, Task
│   ├── display.py           # Terminal UI components
│   ├── logger.py            # Logging setup
│   ├── runner.py            # run() orchestration
│   ├── task.py              # Task dataclass
│   └── worker.py            # Thread-based workers
├── tests/                   # Unit tests
├── example.py               # Runnable demo
└── README.md

🔍 Task Class

Task(
    data="file.txt",          # Any payload (file path, object, ID...)
    name="Optional Name",     # Short label shown in terminal
    desc="Optional Description"  # Longer label shown in terminal
)

Auto-generated defaults when omitted:

• name: file stem if data is a path, else first 16 chars
• desc: "Processing '<filename>'" if path, else truncated string

📋 run() Parameters

Parameter	Type	Required	Default	Description
title	str	✅	—	Header shown in terminal
action	Callable	✅	—	Function called with each task's data
tasks	list[Task]	✅	—	Tasks to process
worker_count	int	❌	2	Number of parallel workers

The action function should return a truthy value on success and falsy on failure.

📄 Logging

• Logs written to logs/tasktracker.log (appended across runs)
• Log level: DEBUG — captures all task start/completion/exception events
• Terminal output is suppressed — terminal stays clean during run

📜 License

MIT

💬 Contact

For issues or contributions, please visit GitHub Issues.