fastapi-progress 0.1.0__tar.gz

fastapi_progress-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.3
+Name: fastapi-progress
+Version: 0.1.0
+Summary: Zero-config background task progress tracker for FastAPI using WebSockets.
+Author: Aldair Andrade
+Author-email: Aldair Andrade <demianmaster2003@gmail.com>
+Requires-Dist: fastapi>=0.138.1
+Requires-Dist: redis>=8.0.1
+Requires-Dist: uvicorn[standard]>=0.49.0
+Requires-Dist: websockets>=16.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# fastapi-progress
+
+A zero-config library to track the progress of FastAPI background tasks and stream it to the frontend via WebSockets in real-time.
+
+## Features
+
+- **Zero-config WebSockets:** Automatically injects a `/ws/progress/{task_id}` endpoint.
+- **Elegant Decorator:** Use `@track_progress` on your background tasks.
+- **Context-aware Updates:** Simply call `await progress.update(50, "Processing")` from anywhere in your task without passing task IDs around.
+- **Hybrid State Backend:** Includes an in-memory backend for simple deployments, and a Redis backend for distributed setups (e.g., Celery, multiple Uvicorn workers).
+
+## Installation
+
+Using `uv` (recommended):
+```bash
+uv add fastapi-progress
+```
+Or pip:
+```bash
+pip install fastapi-progress
+```
+
+## Quick Start
+
+```python
+import asyncio
+import uuid
+from fastapi import FastAPI, BackgroundTasks
+from fastapi_progress import init_progress, track_progress, progress
+
+app = FastAPI()
+
+# 1. Initialize to inject the websocket route
+init_progress(app)
+
+# 2. Decorate your background task
+@track_progress(task_id_param="task_id")
+async def heavy_work(task_id: str):
+    await progress.update(10, "Starting work...")
+    await asyncio.sleep(1)
+    
+    await progress.update(50, "Processing data...")
+    await asyncio.sleep(2)
+    
+    await progress.update(100, "Done!")
+
+# 3. Trigger the task
+@app.post("/do-work")
+async def start_work(tasks: BackgroundTasks):
+    task_id = str(uuid.uuid4())
+    tasks.add_task(heavy_work, task_id=task_id)
+    return {"task_id": task_id}
+```
+
+## Using Redis (For Production)
+
+If you are running multiple Gunicorn/Uvicorn workers, you must use Redis to share the state across processes.
+
+```python
+from redis.asyncio import Redis
+from fastapi_progress import init_progress, RedisBackend
+
+redis_client = Redis(host="localhost", port=6379)
+backend = RedisBackend(redis_client)
+
+init_progress(app, backend=backend)
+```

fastapi_progress-0.1.0/README.md

@@ -0,0 +1,67 @@
+# fastapi-progress
+
+A zero-config library to track the progress of FastAPI background tasks and stream it to the frontend via WebSockets in real-time.
+
+## Features
+
+- **Zero-config WebSockets:** Automatically injects a `/ws/progress/{task_id}` endpoint.
+- **Elegant Decorator:** Use `@track_progress` on your background tasks.
+- **Context-aware Updates:** Simply call `await progress.update(50, "Processing")` from anywhere in your task without passing task IDs around.
+- **Hybrid State Backend:** Includes an in-memory backend for simple deployments, and a Redis backend for distributed setups (e.g., Celery, multiple Uvicorn workers).
+
+## Installation
+
+Using `uv` (recommended):
+```bash
+uv add fastapi-progress
+```
+Or pip:
+```bash
+pip install fastapi-progress
+```
+
+## Quick Start
+
+```python
+import asyncio
+import uuid
+from fastapi import FastAPI, BackgroundTasks
+from fastapi_progress import init_progress, track_progress, progress
+
+app = FastAPI()
+
+# 1. Initialize to inject the websocket route
+init_progress(app)
+
+# 2. Decorate your background task
+@track_progress(task_id_param="task_id")
+async def heavy_work(task_id: str):
+    await progress.update(10, "Starting work...")
+    await asyncio.sleep(1)
+    
+    await progress.update(50, "Processing data...")
+    await asyncio.sleep(2)
+    
+    await progress.update(100, "Done!")
+
+# 3. Trigger the task
+@app.post("/do-work")
+async def start_work(tasks: BackgroundTasks):
+    task_id = str(uuid.uuid4())
+    tasks.add_task(heavy_work, task_id=task_id)
+    return {"task_id": task_id}
+```
+
+## Using Redis (For Production)
+
+If you are running multiple Gunicorn/Uvicorn workers, you must use Redis to share the state across processes.
+
+```python
+from redis.asyncio import Redis
+from fastapi_progress import init_progress, RedisBackend
+
+redis_client = Redis(host="localhost", port=6379)
+backend = RedisBackend(redis_client)
+
+init_progress(app, backend=backend)
+```

fastapi_progress-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "fastapi-progress"
+version = "0.1.0"
+description = "Zero-config background task progress tracker for FastAPI using WebSockets."
+readme = "README.md"
+authors = [
+    { name = "Aldair Andrade", email = "demianmaster2003@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.138.1",
+    "redis>=8.0.1",
+    "uvicorn[standard]>=0.49.0",
+    "websockets>=16.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+]

fastapi_progress-0.1.0/src/fastapi_progress/__init__.py

@@ -0,0 +1,15 @@
+from .core import init_progress
+from .decorators import track_progress
+from .context import progress
+from .state.base import StateBackend
+from .state.memory import MemoryBackend
+from .state.redis import RedisBackend
+
+__all__ = [
+    "init_progress",
+    "track_progress",
+    "progress",
+    "StateBackend",
+    "MemoryBackend",
+    "RedisBackend"
+]

fastapi_progress-0.1.0/src/fastapi_progress/context.py

@@ -0,0 +1,14 @@
+from contextvars import ContextVar
+from typing import Any
+from .globals import get_backend
+
+current_task_id: ContextVar[str | None] = ContextVar("current_task_id", default=None)
+
+class Progress:
+    async def update(self, progress: int, message: str = "", metadata: dict[str, Any] | None = None) -> None:
+        task_id = current_task_id.get()
+        if task_id:
+            backend = get_backend()
+            await backend.update(task_id, progress, message, metadata)
+
+progress = Progress()

fastapi_progress-0.1.0/src/fastapi_progress/core.py

@@ -0,0 +1,29 @@
+from typing import Any
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from .globals import set_backend, get_backend
+from .state.base import StateBackend
+
+def init_progress(app: FastAPI, backend: StateBackend | None = None, prefix: str = "/ws/progress") -> None:
+    if backend:
+        set_backend(backend)
+
+    @app.websocket(f"{prefix}/{{task_id}}")
+    async def progress_websocket(websocket: WebSocket, task_id: str) -> None:
+        await websocket.accept()
+        state_backend = get_backend()
+        
+        try:
+            async for data in state_backend.subscribe(task_id):
+                await websocket.send_json(data)
+                if data.get("progress") == 100 or data.get("message", "").startswith("Error:"):
+                    break
+        except WebSocketDisconnect:
+            pass
+        except Exception:
+            pass
+        finally:
+            try:
+                await websocket.close()
+            except Exception:
+                pass

fastapi_progress-0.1.0/src/fastapi_progress/decorators.py

@@ -0,0 +1,37 @@
+import uuid
+from functools import wraps
+from typing import Callable, Any, Coroutine, TypeVar, ParamSpec
+
+from .context import current_task_id
+from .globals import get_backend
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def track_progress(task_id_param: str | None = None) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
+    def decorator(func: Callable[P, Coroutine[Any, Any, R]]) -> Callable[P, Coroutine[Any, Any, R]]:
+        @wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            task_id = None
+            if task_id_param and task_id_param in kwargs:
+                task_id = str(kwargs[task_id_param])
+            else:
+                task_id = str(uuid.uuid4())
+
+            token = current_task_id.set(task_id)
+            backend = get_backend()
+
+            await backend.update(task_id, 0, "Task started")
+
+            try:
+                result = await func(*args, **kwargs)
+                await backend.update(task_id, 100, "Task completed")
+                return result
+            except Exception as e:
+                await backend.update(task_id, 0, f"Error: {str(e)}")
+                raise e
+            finally:
+                current_task_id.reset(token)
+
+        return wrapper
+    return decorator

fastapi_progress-0.1.0/src/fastapi_progress/globals.py

@@ -0,0 +1,11 @@
+from .state.base import StateBackend
+from .state.memory import MemoryBackend
+
+_active_backend: StateBackend = MemoryBackend()
+
+def set_backend(backend: StateBackend) -> None:
+    global _active_backend
+    _active_backend = backend
+
+def get_backend() -> StateBackend:
+    return _active_backend

fastapi_progress-0.1.0/src/fastapi_progress/state/__init__.py

@@ -0,0 +1,5 @@
+from .base import StateBackend
+from .memory import MemoryBackend
+from .redis import RedisBackend
+
+__all__ = ["StateBackend", "MemoryBackend", "RedisBackend"]

fastapi_progress-0.1.0/src/fastapi_progress/state/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Any
+
+class StateBackend(ABC):
+    @abstractmethod
+    async def update(self, task_id: str, progress: int, message: str = "", metadata: dict[str, Any] | None = None) -> None:
+        pass
+
+    @abstractmethod
+    async def get(self, task_id: str) -> dict[str, Any] | None:
+        pass
+
+    @abstractmethod
+    async def subscribe(self, task_id: str) -> AsyncGenerator[dict[str, Any], None]:
+        pass

fastapi_progress-0.1.0/src/fastapi_progress/state/memory.py

@@ -0,0 +1,47 @@
+import asyncio
+from typing import AsyncGenerator, Any
+from .base import StateBackend
+
+class MemoryBackend(StateBackend):
+    def __init__(self):
+        self._state: dict[str, dict[str, Any]] = {}
+        self._subscriptions: dict[str, list[asyncio.Queue]] = {}
+
+    async def update(self, task_id: str, progress: int, message: str = "", metadata: dict[str, Any] | None = None) -> None:
+        data = {
+            "task_id": task_id,
+            "progress": progress,
+            "message": message,
+            "metadata": metadata or {}
+        }
+        self._state[task_id] = data
+        
+        if task_id in self._subscriptions:
+            for queue in self._subscriptions[task_id]:
+                await queue.put(data)
+
+    async def get(self, task_id: str) -> dict[str, Any] | None:
+        return self._state.get(task_id)
+
+    async def subscribe(self, task_id: str) -> AsyncGenerator[dict[str, Any], None]:
+        queue = asyncio.Queue()
+        if task_id not in self._subscriptions:
+            self._subscriptions[task_id] = []
+        self._subscriptions[task_id].append(queue)
+        
+        try:
+            current = await self.get(task_id)
+            if current:
+                yield current
+                
+            while True:
+                data = await queue.get()
+                yield data
+        finally:
+            if task_id in self._subscriptions:
+                try:
+                    self._subscriptions[task_id].remove(queue)
+                except ValueError:
+                    pass
+                if not self._subscriptions[task_id]:
+                    del self._subscriptions[task_id]

fastapi_progress-0.1.0/src/fastapi_progress/state/redis.py

@@ -0,0 +1,54 @@
+import json
+from typing import AsyncGenerator, Any
+from .base import StateBackend
+
+try:
+    from redis.asyncio import Redis
+except ImportError:
+    Redis = Any
+
+class RedisBackend(StateBackend):
+    def __init__(self, redis_client: 'Redis', prefix: str = "fastapi_progress"):
+        self.redis = redis_client
+        self.prefix = prefix
+
+    def _key(self, task_id: str) -> str:
+        return f"{self.prefix}:state:{task_id}"
+
+    def _channel(self, task_id: str) -> str:
+        return f"{self.prefix}:channel:{task_id}"
+
+    async def update(self, task_id: str, progress: int, message: str = "", metadata: dict[str, Any] | None = None) -> None:
+        data = {
+            "task_id": task_id,
+            "progress": progress,
+            "message": message,
+            "metadata": metadata or {}
+        }
+        payload = json.dumps(data)
+        
+        await self.redis.setex(self._key(task_id), 86400, payload)
+        await self.redis.publish(self._channel(task_id), payload)
+
+    async def get(self, task_id: str) -> dict[str, Any] | None:
+        payload = await self.redis.get(self._key(task_id))
+        if payload:
+            return json.loads(payload)
+        return None
+
+    async def subscribe(self, task_id: str) -> AsyncGenerator[dict[str, Any], None]:
+        pubsub = self.redis.pubsub()
+        await pubsub.subscribe(self._channel(task_id))
+        
+        try:
+            current = await self.get(task_id)
+            if current:
+                yield current
+                
+            async for message in pubsub.listen():
+                if message["type"] == "message":
+                    data = json.loads(message["data"])
+                    yield data
+        finally:
+            await pubsub.unsubscribe(self._channel(task_id))
+            await pubsub.close()