streamator 0.1.1__tar.gz

streamator-0.1.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: streamator
+Version: 0.1.1
+Summary: Backend logging primitive for long-running async jobs
+Author-email: Arved Klöhn <arved.kloehn@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Redundando/streamator
+Project-URL: Repository, https://github.com/Redundando/streamator
+Keywords: streaming,logging,sse,fastapi,async
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dynamo
+Requires-Dist: dynamorator>=0.1.6; extra == "dynamo"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.133.1; extra == "fastapi"
+
+# streamator
+
+Backend logging primitive for long-running async jobs. Stream timestamped log messages
+to a browser UI via SSE or polling — no WebSockets, no custom infrastructure.
+
+Pairs with [`streamator-react`](https://www.npmjs.com/package/streamator-react) on the frontend.
+
+## Install
+
+```bash
+pip install streamator                    # core only (in-memory)
+pip install streamator[fastapi]           # + FastAPI route helpers
+pip install streamator[dynamo]            # + DynamoDB backend
+pip install streamator[fastapi,dynamo]    # everything
+```
+
+## Usage
+
+```python
+from streamator import JobLogger
+
+async def my_job(logger: JobLogger):
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+    logger.close()
+
+@router.post("/start")
+async def start():
+    logger = JobLogger()
+    asyncio.create_task(my_job(logger))
+    return {"log_job_id": logger.job_id}
+```
+
+Or use the context manager — `close()` is called automatically, even on exception:
+
+```python
+async with JobLogger() as logger:
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+```
+
+## FastAPI integration
+
+```python
+from streamator.fastapi import add_log_routes
+
+add_log_routes(app, prefix="/log")
+# GET /log/{job_id}/stream  → SSE stream
+# GET /log/{job_id}         → { logs: [...] } snapshot
+```
+
+## Storage backends
+
+**Memory** (default) — `asyncio.Queue`, SSE push, zero dependencies, single-process only.
+
+**DynamoDB** — persists across restarts, readable by polling, distributed-friendly.
+
+```python
+logger = JobLogger(store="dynamo", table="my-logs-table", ttl_days=1)
+```
+
+## Log levels
+
+`"info"` (default) · `"success"` · `"warning"` · `"error"`
+
+## Log entry format
+
+```python
+{"event": "log", "message": "...", "level": "info", "t": 1.23}
+```
+
+`t` is seconds since the logger was created, computed at the moment `log()` is called.

streamator-0.1.1/README.md

@@ -0,0 +1,74 @@
+# streamator
+
+Backend logging primitive for long-running async jobs. Stream timestamped log messages
+to a browser UI via SSE or polling — no WebSockets, no custom infrastructure.
+
+Pairs with [`streamator-react`](https://www.npmjs.com/package/streamator-react) on the frontend.
+
+## Install
+
+```bash
+pip install streamator                    # core only (in-memory)
+pip install streamator[fastapi]           # + FastAPI route helpers
+pip install streamator[dynamo]            # + DynamoDB backend
+pip install streamator[fastapi,dynamo]    # everything
+```
+
+## Usage
+
+```python
+from streamator import JobLogger
+
+async def my_job(logger: JobLogger):
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+    logger.close()
+
+@router.post("/start")
+async def start():
+    logger = JobLogger()
+    asyncio.create_task(my_job(logger))
+    return {"log_job_id": logger.job_id}
+```
+
+Or use the context manager — `close()` is called automatically, even on exception:
+
+```python
+async with JobLogger() as logger:
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+```
+
+## FastAPI integration
+
+```python
+from streamator.fastapi import add_log_routes
+
+add_log_routes(app, prefix="/log")
+# GET /log/{job_id}/stream  → SSE stream
+# GET /log/{job_id}         → { logs: [...] } snapshot
+```
+
+## Storage backends
+
+**Memory** (default) — `asyncio.Queue`, SSE push, zero dependencies, single-process only.
+
+**DynamoDB** — persists across restarts, readable by polling, distributed-friendly.
+
+```python
+logger = JobLogger(store="dynamo", table="my-logs-table", ttl_days=1)
+```
+
+## Log levels
+
+`"info"` (default) · `"success"` · `"warning"` · `"error"`
+
+## Log entry format
+
+```python
+{"event": "log", "message": "...", "level": "info", "t": 1.23}
+```
+
+`t` is seconds since the logger was created, computed at the moment `log()` is called.

streamator-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "streamator"
+version = "0.1.1"
+description = "Backend logging primitive for long-running async jobs"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Arved Klöhn", email = "arved.kloehn@gmail.com" }]
+keywords = ["streaming", "logging", "sse", "fastapi", "async"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Redundando/streamator"
+Repository = "https://github.com/Redundando/streamator"
+
+[project.optional-dependencies]
+dynamo  = ["dynamorator>=0.1.6"]
+fastapi = ["fastapi>=0.133.1"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

streamator-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

streamator-0.1.1/streamator/__init__.py

@@ -0,0 +1,3 @@
+from .logger import JobLogger
+
+__all__ = ["JobLogger"]

streamator-0.1.1/streamator/fastapi.py

@@ -0,0 +1,45 @@
+import json
+
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse, JSONResponse
+
+from .logger import JobLogger
+
+_loggers: dict[str, JobLogger] = {}
+
+
+def _get(job_id: str) -> JobLogger | None:
+    return _loggers.get(job_id)
+
+
+async def _sse_generator(logger: JobLogger):
+    async for entry in logger._store.stream():
+        yield f"data: {json.dumps(entry)}\n\n"
+    yield f"data: {json.dumps({'event': 'done'})}\n\n"
+    _loggers.pop(logger.job_id, None)
+
+
+def make_stream_response(job_id: str) -> StreamingResponse:
+    logger = _get(job_id)
+    if logger is None:
+        return JSONResponse({"error": "not found"}, status_code=404)
+    return StreamingResponse(
+        _sse_generator(logger),
+        media_type="text/event-stream",
+    )
+
+
+def add_log_routes(app: FastAPI, prefix: str = "/log"):
+    @app.get(f"{prefix}/{{job_id}}/stream")
+    async def stream(job_id: str):
+        return make_stream_response(job_id)
+
+    @app.get(f"{prefix}/{{job_id}}")
+    async def snapshot(job_id: str):
+        logger = _get(job_id)
+        if logger is None:
+            return JSONResponse({"error": "not found"}, status_code=404)
+        logs = logger._store.snapshot()
+        if logger._store._closed:
+            logs = logs + [{"event": "done"}]
+        return {"logs": logs}

streamator-0.1.1/streamator/logger.py

@@ -0,0 +1,45 @@
+import time
+import uuid
+
+from .store import MemoryStore, DynamoStore
+
+class JobLogger:
+    def __init__(self, store="memory", **kwargs):
+        self.job_id = str(uuid.uuid4())
+        self.start_t = time.monotonic()
+
+        if store == "memory":
+            self._store = MemoryStore()
+        elif store == "dynamo":
+            self._store = DynamoStore(
+                table=kwargs["table"],
+                ttl_days=kwargs.get("ttl_days", 7),
+            )
+            self._store.set_key(self.job_id)
+        else:
+            raise ValueError(f"Unknown store: {store!r}")
+
+        try:
+            from . import fastapi as _fa
+            _fa._loggers[self.job_id] = self
+        except ImportError:
+            pass
+
+    def log(self, message: str, level: str = "info"):
+        entry = {
+            "event": "log",
+            "message": message,
+            "level": level,
+            "t": round(time.monotonic() - self.start_t, 3),
+        }
+        self._store.append(entry)
+
+    def close(self):
+        self._store.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        self.close()
+

streamator-0.1.1/streamator/store.py

@@ -0,0 +1,50 @@
+import asyncio
+
+
+class MemoryStore:
+    def __init__(self):
+        self._queue = asyncio.Queue()
+        self._log = []
+        self._closed = False
+
+    def append(self, entry: dict):
+        self._log.append(entry)
+        self._queue.put_nowait(entry)
+
+    async def stream(self):
+        while True:
+            entry = await self._queue.get()
+            if entry is None:
+                break
+            yield entry
+
+    def snapshot(self) -> list:
+        return list(self._log)
+
+    def close(self):
+        self._closed = True
+        self._queue.put_nowait(None)
+
+
+class DynamoStore:
+    def __init__(self, table: str, ttl_days: float = 7):
+        from dynamorator import DynamoDBStore
+        self._store = DynamoDBStore(table_name=table)
+        self._ttl_days = ttl_days
+        self._key = None
+        self._closed = False
+
+    def set_key(self, job_id: str):
+        self._key = job_id
+
+    def append(self, entry: dict):
+        existing = self._store.get(self._key) or {"logs": []}
+        existing["logs"].append(entry)
+        self._store.put(self._key, existing, ttl_days=self._ttl_days)
+
+    def close(self):
+        self._closed = True
+
+    def snapshot(self) -> list:
+        data = self._store.get(self._key)
+        return data["logs"] if data else []

streamator-0.1.1/streamator.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: streamator
+Version: 0.1.1
+Summary: Backend logging primitive for long-running async jobs
+Author-email: Arved Klöhn <arved.kloehn@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Redundando/streamator
+Project-URL: Repository, https://github.com/Redundando/streamator
+Keywords: streaming,logging,sse,fastapi,async
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dynamo
+Requires-Dist: dynamorator>=0.1.6; extra == "dynamo"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.133.1; extra == "fastapi"
+
+# streamator
+
+Backend logging primitive for long-running async jobs. Stream timestamped log messages
+to a browser UI via SSE or polling — no WebSockets, no custom infrastructure.
+
+Pairs with [`streamator-react`](https://www.npmjs.com/package/streamator-react) on the frontend.
+
+## Install
+
+```bash
+pip install streamator                    # core only (in-memory)
+pip install streamator[fastapi]           # + FastAPI route helpers
+pip install streamator[dynamo]            # + DynamoDB backend
+pip install streamator[fastapi,dynamo]    # everything
+```
+
+## Usage
+
+```python
+from streamator import JobLogger
+
+async def my_job(logger: JobLogger):
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+    logger.close()
+
+@router.post("/start")
+async def start():
+    logger = JobLogger()
+    asyncio.create_task(my_job(logger))
+    return {"log_job_id": logger.job_id}
+```
+
+Or use the context manager — `close()` is called automatically, even on exception:
+
+```python
+async with JobLogger() as logger:
+    logger.log("Starting…")
+    await do_work()
+    logger.log("Done", level="success")
+```
+
+## FastAPI integration
+
+```python
+from streamator.fastapi import add_log_routes
+
+add_log_routes(app, prefix="/log")
+# GET /log/{job_id}/stream  → SSE stream
+# GET /log/{job_id}         → { logs: [...] } snapshot
+```
+
+## Storage backends
+
+**Memory** (default) — `asyncio.Queue`, SSE push, zero dependencies, single-process only.
+
+**DynamoDB** — persists across restarts, readable by polling, distributed-friendly.
+
+```python
+logger = JobLogger(store="dynamo", table="my-logs-table", ttl_days=1)
+```
+
+## Log levels
+
+`"info"` (default) · `"success"` · `"warning"` · `"error"`
+
+## Log entry format
+
+```python
+{"event": "log", "message": "...", "level": "info", "t": 1.23}
+```
+
+`t` is seconds since the logger was created, computed at the moment `log()` is called.

streamator-0.1.1/streamator.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+streamator/__init__.py
+streamator/fastapi.py
+streamator/logger.py
+streamator/store.py
+streamator.egg-info/PKG-INFO
+streamator.egg-info/SOURCES.txt
+streamator.egg-info/dependency_links.txt
+streamator.egg-info/requires.txt
+streamator.egg-info/top_level.txt
+tests/test_backend.py

streamator-0.1.1/streamator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

streamator-0.1.1/streamator.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dynamo]
+dynamorator>=0.1.6
+
+[fastapi]
+fastapi>=0.133.1

streamator-0.1.1/streamator.egg-info/top_level.txt

@@ -0,0 +1 @@
+streamator

streamator-0.1.1/tests/test_backend.py

@@ -0,0 +1,99 @@
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from streamator import JobLogger
+from streamator import fastapi as sf
+
+
+@pytest.fixture(autouse=True)
+def clear_registry():
+    sf._loggers.clear()
+    yield
+    sf._loggers.clear()
+
+
+# --- JobLogger ---
+
+def test_job_id_is_unique():
+    a, b = JobLogger(), JobLogger()
+    assert a.job_id != b.job_id
+
+
+def test_log_entry_shape():
+    logger = JobLogger()
+    logger.log("hello")
+    entries = logger._store.snapshot()
+    assert len(entries) == 1
+    e = entries[0]
+    assert e["event"] == "log"
+    assert e["message"] == "hello"
+    assert e["level"] == "info"
+    assert isinstance(e["t"], float)
+
+
+def test_log_levels():
+    logger = JobLogger()
+    for level in ("info", "success", "warning", "error"):
+        logger.log("msg", level=level)
+    levels = [e["level"] for e in logger._store.snapshot()]
+    assert levels == ["info", "success", "warning", "error"]
+
+
+# --- MemoryStore streaming ---
+
+async def test_memory_store_stream():
+    logger = JobLogger()
+    logger.log("a")
+    logger.log("b")
+    logger.close()
+
+    received = []
+    async for entry in logger._store.stream():
+        received.append(entry["message"])
+
+    assert received == ["a", "b"]
+
+
+# --- FastAPI routes ---
+
+@pytest.fixture
+def app_client():
+    app = FastAPI()
+    sf.add_log_routes(app)
+    return TestClient(app)
+
+
+def test_snapshot_route(app_client):
+    logger = JobLogger()
+    logger.log("step 1")
+    logger.log("step 2")
+
+    resp = app_client.get(f"/log/{logger.job_id}")
+    assert resp.status_code == 200
+    logs = resp.json()["logs"]
+    assert len(logs) == 2
+    assert logs[0]["message"] == "step 1"
+
+
+def test_snapshot_not_found(app_client):
+    resp = app_client.get("/log/nonexistent")
+    assert resp.status_code == 404
+
+
+def test_stream_route(app_client):
+    logger = JobLogger()
+    logger.log("streamed")
+    logger.close()
+
+    with app_client.stream("GET", f"/log/{logger.job_id}/stream") as resp:
+        assert resp.status_code == 200
+        chunks = list(resp.iter_lines())
+
+    data_lines = [l for l in chunks if l.startswith("data:")]
+    assert any("streamed" in l for l in data_lines)
+
+
+def test_stream_not_found(app_client):
+    resp = app_client.get("/log/nonexistent/stream")
+    assert resp.status_code == 404