asynclet 0.1.0__tar.gz

asynclet-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+*.local
+
+# Hatch / build artifacts (if any stray)
+wheels/

asynclet-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: asynclet
+Version: 0.1.0
+Summary: Async task layer for Streamlit: background sync/async work, polling, progress, cancellation
+Project-URL: Homepage, https://github.com/asynclet/asynclet
+Author: asynclet contributors
+License-Expression: MIT
+Keywords: async,background,streamlit,tasks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: asyncer>=0.0.2
+Requires-Dist: janus>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: streamlit>=1.33.0; extra == 'dev'
+Provides-Extra: scheduler
+Requires-Dist: apscheduler>=3.10.0; extra == 'scheduler'
+Provides-Extra: streamlit
+Requires-Dist: streamlit>=1.28.0; extra == 'streamlit'
+Description-Content-Type: text/markdown
+
+# asynclet
+
+Small **async task layer** for [Streamlit](https://streamlit.io/) (and similar “sync main thread + rerun” UIs): run sync or async work on a **dedicated background event loop**, then **poll** status, results, **progress**, and **cancellation** without blocking the UI thread.
+
+## Install
+
+```bash
+pip install asynclet
+```
+
+Optional extras:
+
+- **Streamlit** (for a typical app environment): `pip install 'asynclet[streamlit]'`
+- **APScheduler** (optional timers/jobs): `pip install 'asynclet[scheduler]'`
+
+Requires **Python 3.9+**.
+
+## Quick start
+
+```python
+import streamlit as st
+import asynclet
+
+task = asynclet.run(fetch_data)
+
+if task.done:
+    st.write(task.result)
+else:
+    st.write("Loading…")
+```
+
+On each rerun, check `task.done` and read `task.result` when finished.
+
+## Public API
+
+| Item | Role |
+|------|------|
+| `asynclet.run(func, /, *args, manager=None, **kwargs)` | Submit `func` on the worker; returns a `Task`. |
+| `Task.done` | Whether the result (or error) is ready. |
+| `Task.result` | Result value; raises if not complete. |
+| `Task.status` | `TaskStatus`: `PENDING`, `RUNNING`, `DONE`, `ERROR`, `CANCELLED`. |
+| `Task.error` | Exception object when `status` is `ERROR`, else `None`. |
+| `Task.cancel()` | Request cancellation (running tasks use asyncio cancellation; pending tasks cancel the result future). |
+| `Task.progress` | Non-blocking drain of progress values (see below). |
+| `TaskManager` / `get_default_manager()` | Custom registry and `cleanup()` when you keep many completed tasks. |
+| `session_tasks(session_state)` | Dict stored on `st.session_state` for named tasks. |
+
+## Progress (Janus)
+
+For **async** functions only, declare a parameter named **`queue`** or **`progress_queue`**. If it is the **first** parameter, remaining positional arguments to `run()` map to the rest of the signature.
+
+```python
+async def job(queue, steps: int):
+    for i in range(steps):
+        await queue.async_q.put(i)
+    return steps
+
+task = asynclet.run(job, 10)
+# Each rerun:
+for x in task.progress:
+    st.write(x)
+```
+
+The UI thread reads via `task.progress`, which pulls from the sync side of a [janus](https://github.com/aio-libs/janus) queue.
+
+## Streamlit session state
+
+```python
+import streamlit as st
+import asynclet
+
+tasks = asynclet.session_tasks(st.session_state)
+if "load" not in tasks:
+    tasks["load"] = asynclet.run(load_data)
+
+task = tasks["load"]
+```
+
+## How it works (short)
+
+- One **daemon thread** runs a single **asyncio** event loop.
+- **Async** callables run on that loop; **sync** callables run via [asyncer](https://github.com/tiangolo/asyncer)’s `asyncify` (thread pool).
+- Submissions use `asyncio.run_coroutine_threadsafe`; results are bridged with a `concurrent.futures.Future` for the polling API.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+The **dev** extra includes Streamlit so CI can run headless **[AppTest](https://docs.streamlit.io/develop/api-reference/app-testing)** checks in `tests/test_streamlit_apptest.py` against the sample apps under `tests/streamlit_apps/`.
+
+## License
+
+MIT.

asynclet-0.1.0/README.md

@@ -0,0 +1,96 @@
+# asynclet
+
+Small **async task layer** for [Streamlit](https://streamlit.io/) (and similar “sync main thread + rerun” UIs): run sync or async work on a **dedicated background event loop**, then **poll** status, results, **progress**, and **cancellation** without blocking the UI thread.
+
+## Install
+
+```bash
+pip install asynclet
+```
+
+Optional extras:
+
+- **Streamlit** (for a typical app environment): `pip install 'asynclet[streamlit]'`
+- **APScheduler** (optional timers/jobs): `pip install 'asynclet[scheduler]'`
+
+Requires **Python 3.9+**.
+
+## Quick start
+
+```python
+import streamlit as st
+import asynclet
+
+task = asynclet.run(fetch_data)
+
+if task.done:
+    st.write(task.result)
+else:
+    st.write("Loading…")
+```
+
+On each rerun, check `task.done` and read `task.result` when finished.
+
+## Public API
+
+| Item | Role |
+|------|------|
+| `asynclet.run(func, /, *args, manager=None, **kwargs)` | Submit `func` on the worker; returns a `Task`. |
+| `Task.done` | Whether the result (or error) is ready. |
+| `Task.result` | Result value; raises if not complete. |
+| `Task.status` | `TaskStatus`: `PENDING`, `RUNNING`, `DONE`, `ERROR`, `CANCELLED`. |
+| `Task.error` | Exception object when `status` is `ERROR`, else `None`. |
+| `Task.cancel()` | Request cancellation (running tasks use asyncio cancellation; pending tasks cancel the result future). |
+| `Task.progress` | Non-blocking drain of progress values (see below). |
+| `TaskManager` / `get_default_manager()` | Custom registry and `cleanup()` when you keep many completed tasks. |
+| `session_tasks(session_state)` | Dict stored on `st.session_state` for named tasks. |
+
+## Progress (Janus)
+
+For **async** functions only, declare a parameter named **`queue`** or **`progress_queue`**. If it is the **first** parameter, remaining positional arguments to `run()` map to the rest of the signature.
+
+```python
+async def job(queue, steps: int):
+    for i in range(steps):
+        await queue.async_q.put(i)
+    return steps
+
+task = asynclet.run(job, 10)
+# Each rerun:
+for x in task.progress:
+    st.write(x)
+```
+
+The UI thread reads via `task.progress`, which pulls from the sync side of a [janus](https://github.com/aio-libs/janus) queue.
+
+## Streamlit session state
+
+```python
+import streamlit as st
+import asynclet
+
+tasks = asynclet.session_tasks(st.session_state)
+if "load" not in tasks:
+    tasks["load"] = asynclet.run(load_data)
+
+task = tasks["load"]
+```
+
+## How it works (short)
+
+- One **daemon thread** runs a single **asyncio** event loop.
+- **Async** callables run on that loop; **sync** callables run via [asyncer](https://github.com/tiangolo/asyncer)’s `asyncify` (thread pool).
+- Submissions use `asyncio.run_coroutine_threadsafe`; results are bridged with a `concurrent.futures.Future` for the polling API.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+The **dev** extra includes Streamlit so CI can run headless **[AppTest](https://docs.streamlit.io/develop/api-reference/app-testing)** checks in `tests/test_streamlit_apptest.py` against the sample apps under `tests/streamlit_apps/`.
+
+## License
+
+MIT.

asynclet-0.1.0/asynclet/__init__.py

@@ -0,0 +1,16 @@
+"""Async task layer for Streamlit: background execution, polling, progress, cancellation."""
+
+from asynclet.manager import TaskManager, get_default_manager, run
+from asynclet.session import session_tasks
+from asynclet.task import Task, TaskStatus
+
+__all__ = [
+    "Task",
+    "TaskStatus",
+    "TaskManager",
+    "get_default_manager",
+    "run",
+    "session_tasks",
+]
+
+__version__ = "0.1.0"

asynclet-0.1.0/asynclet/manager.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import queue
+import threading
+from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
+
+from asyncer import asyncify
+
+from asynclet.task import Task, TaskStatus, new_task_id
+from asynclet.worker import submit_coro
+
+T = TypeVar("T")
+
+_default_manager: Optional["TaskManager"] = None
+_default_manager_lock = threading.Lock()
+
+
+def _bind_progress_queue(
+    func: Callable[..., Any],
+    queue: Any,
+    args: Tuple[Any, ...],
+    kwargs: Dict[str, Any],
+) -> Tuple[Tuple[Any, ...], Dict[str, Any]]:
+    """Pass the Janus queue as the first positional arg if named ``queue`` / ``progress_queue``, else as a keyword."""
+    sig = inspect.signature(func)
+    params = list(sig.parameters.keys())
+    if not params:
+        return args, kwargs
+    first = params[0]
+    if first in ("progress_queue", "queue"):
+        kw = {k: v for k, v in kwargs.items() if k not in ("progress_queue", "queue")}
+        return (queue,) + args, kw
+    if "progress_queue" in sig.parameters:
+        return args, {**kwargs, "progress_queue": queue}
+    if "queue" in sig.parameters:
+        return args, {**kwargs, "queue": queue}
+    return args, kwargs
+
+
+def _wants_progress_queue(func: Callable[..., Any]) -> bool:
+    if not inspect.iscoroutinefunction(func):
+        return False
+    sig = inspect.signature(func)
+    return "progress_queue" in sig.parameters or "queue" in sig.parameters
+
+
+class TaskManager:
+    """Submits work to the asynclet worker, tracks tasks, and trims completed entries."""
+
+    def __init__(self, *, max_completed: int = 256) -> None:
+        self._tasks: Dict[str, Task[Any]] = {}
+        self._lock = threading.Lock()
+        self._max_completed = max_completed
+
+    def submit(self, func: Callable[..., T], /, *args: Any, **kwargs: Any) -> Task[T]:
+        task_id = new_task_id()
+        task: Task[T] = Task(task_id)
+        with self._lock:
+            self._tasks[task_id] = task
+        submit_coro(self._execute(task, func, args, kwargs))
+        self._cleanup_if_needed()
+        return task
+
+    def get(self, task_id: str) -> Optional[Task[Any]]:
+        with self._lock:
+            return self._tasks.get(task_id)
+
+    def cleanup(self) -> int:
+        """Remove oldest completed tasks if the registry exceeds ``max_completed``."""
+        removed = 0
+        with self._lock:
+            done_ids = [tid for tid, t in self._tasks.items() if t.done]
+            overflow = len(done_ids) - self._max_completed
+            if overflow <= 0:
+                return 0
+            for tid in done_ids[:overflow]:
+                self._tasks.pop(tid, None)
+                removed += 1
+        return removed
+
+    def _cleanup_if_needed(self) -> None:
+        with self._lock:
+            completed = sum(1 for t in self._tasks.values() if t.done)
+        if completed > self._max_completed:
+            self.cleanup()
+
+    async def _execute(
+        self,
+        task: Task[Any],
+        func: Callable[..., Any],
+        args: Tuple[Any, ...],
+        kwargs: Dict[str, Any],
+    ) -> None:
+        progress_q = None
+        try:
+            current = asyncio.current_task()
+            if current is None:
+                raise RuntimeError("asynclet: missing asyncio task")
+            loop = asyncio.get_running_loop()
+            task._bind_worker_task(current, loop)
+            if task.status == TaskStatus.CANCELLED:
+                raise asyncio.CancelledError
+
+            if inspect.iscoroutinefunction(func):
+                if _wants_progress_queue(func):
+                    import janus
+
+                    progress_q = janus.Queue()
+                    task._set_progress_queue(progress_q)
+                    args, kwargs = _bind_progress_queue(func, progress_q, args, kwargs)
+                result = await func(*args, **kwargs)
+            else:
+                runner = asyncify(func)
+                result = await runner(*args, **kwargs)
+
+            if task.status != TaskStatus.CANCELLED:
+                task._complete_ok(result)
+        except asyncio.CancelledError:
+            task._complete_cancelled()
+        except Exception as exc:
+            if task.status != TaskStatus.CANCELLED:
+                task._complete_error(exc)
+        finally:
+            if progress_q is not None:
+                tail: List[Any] = []
+                while True:
+                    try:
+                        tail.append(progress_q.sync_q.get_nowait())
+                    except queue.Empty:
+                        break
+                task._buffer_progress_tail(tail)
+                progress_q.close()
+                await progress_q.wait_closed()
+            task._clear_progress_queue_ref()
+
+    def register_global(self, task: Task[Any], name: str) -> None:
+        """Alias a task for shared lookup (e.g. ``get(f'global:{name}')``)."""
+        with self._lock:
+            self._tasks[f"global:{name}"] = task
+
+
+def get_default_manager() -> TaskManager:
+    global _default_manager
+    with _default_manager_lock:
+        if _default_manager is None:
+            _default_manager = TaskManager()
+        return _default_manager
+
+
+def run(
+    func: Callable[..., T],
+    /,
+    *args: Any,
+    manager: Optional[TaskManager] = None,
+    **kwargs: Any,
+) -> Task[T]:
+    """
+    Run ``func`` on the asynclet worker thread.
+
+    Async functions run on the worker event loop. Sync functions run via ``asyncer.asyncify``
+    (thread pool). If the coroutine declares a ``progress_queue`` or ``queue`` parameter, a
+    :class:`janus.Queue` is created and injected for streaming progress to the UI thread.
+    """
+    m = manager or get_default_manager()
+    return m.submit(func, *args, **kwargs)

asynclet-0.1.0/asynclet/scheduler.py

@@ -0,0 +1,18 @@
+"""
+Optional APScheduler integration — install with ``pip install 'asynclet[scheduler]'``.
+
+To drive timers on the same loop as asynclet tasks, obtain the loop with
+``asynclet.worker.get_worker_loop()`` and configure ``AsyncIOScheduler`` with that loop
+(see APScheduler docs for ``AsyncIOScheduler(event_loop=...)``).
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+try:  # pragma: no branch - optional dependency
+    from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+    __all__.append("AsyncIOScheduler")
+except ImportError:
+    AsyncIOScheduler = None  # type: ignore[misc,assignment]

asynclet-0.1.0/asynclet/session.py

@@ -0,0 +1,25 @@
+"""Streamlit session helpers (no hard dependency on Streamlit — pass ``st.session_state``)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, MutableMapping
+
+
+def session_tasks(
+    session_state: MutableMapping[str, Any],
+    key: str = "asynclet_tasks",
+) -> Dict[str, Any]:
+    """
+    Return a task registry dict stored on ``session_state[key]``.
+
+    Example::
+
+        import streamlit as st
+        import asynclet
+
+        tasks = asynclet.session_tasks(st.session_state)
+        tasks["fetch"] = asynclet.run(load_data)
+    """
+    if key not in session_state:
+        session_state[key] = {}
+    return session_state[key]

asynclet-0.1.0/asynclet/task.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+import uuid
+from concurrent import futures
+from enum import Enum
+from typing import Any, Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class TaskStatus(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    ERROR = "error"
+    CANCELLED = "cancelled"
+
+
+class Task(Generic[T]):
+    """Handle for work running on the asynclet worker loop."""
+
+    def __init__(self, task_id: str) -> None:
+        self.id = task_id
+        self._status = TaskStatus.PENDING
+        self._result_fut: futures.Future[T] = futures.Future()
+        self._error: Optional[BaseException] = None
+        self._progress_queue: Any = None
+        self._progress_tail: List[Any] = []
+        self._asyncio_task: Optional[asyncio.Task[Any]] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._lock = threading.Lock()
+
+    @property
+    def status(self) -> TaskStatus:
+        return self._status
+
+    @property
+    def done(self) -> bool:
+        return self._result_fut.done()
+
+    @property
+    def result(self) -> T:
+        if not self._result_fut.done():
+            raise RuntimeError("Task is not complete")
+        return self._result_fut.result()
+
+    @property
+    def error(self) -> Optional[BaseException]:
+        return self._error
+
+    @property
+    def progress(self) -> List[Any]:
+        """Drain pending progress values (non-blocking) from the Janus queue and any buffered tail."""
+        out: List[Any] = []
+        q = self._progress_queue
+        if q is not None:
+            sync_q = q.sync_q
+            while True:
+                try:
+                    out.append(sync_q.get_nowait())
+                except queue.Empty:
+                    break
+        if self._progress_tail:
+            out.extend(self._progress_tail)
+            self._progress_tail.clear()
+        return out
+
+    def cancel(self) -> bool:
+        """Request cancellation. Returns True if cancellation was scheduled or the result future was cancelled."""
+        with self._lock:
+            if self._status in (TaskStatus.DONE, TaskStatus.ERROR, TaskStatus.CANCELLED):
+                return False
+            aio_task = self._asyncio_task
+            loop = self._loop
+            pending = self._status == TaskStatus.PENDING
+        if aio_task is not None and loop is not None and not aio_task.done():
+
+            def _cancel() -> None:
+                aio_task.cancel()
+
+            loop.call_soon_threadsafe(_cancel)
+            return True
+        if pending:
+            with self._lock:
+                self._status = TaskStatus.CANCELLED
+            return self._result_fut.cancel()
+        return False
+
+    def _bind_worker_task(self, aio_task: asyncio.Task[Any], loop: asyncio.AbstractEventLoop) -> None:
+        with self._lock:
+            self._asyncio_task = aio_task
+            self._loop = loop
+            if self._status != TaskStatus.CANCELLED:
+                self._status = TaskStatus.RUNNING
+
+    def _set_progress_queue(self, queue_obj: Any) -> None:
+        self._progress_queue = queue_obj
+
+    def _clear_progress_queue_ref(self) -> None:
+        self._progress_queue = None
+
+    def _buffer_progress_tail(self, items: List[Any]) -> None:
+        if items:
+            self._progress_tail.extend(items)
+
+    def _complete_ok(self, value: T) -> None:
+        with self._lock:
+            if self._status == TaskStatus.CANCELLED:
+                return
+            self._status = TaskStatus.DONE
+        if not self._result_fut.done():
+            self._result_fut.set_result(value)
+
+    def _complete_error(self, exc: BaseException) -> None:
+        with self._lock:
+            if self._status == TaskStatus.CANCELLED:
+                return
+            self._status = TaskStatus.ERROR
+            self._error = exc
+        if not self._result_fut.done():
+            self._result_fut.set_exception(exc)
+
+    def _complete_cancelled(self) -> None:
+        with self._lock:
+            self._status = TaskStatus.CANCELLED
+        if not self._result_fut.done():
+            self._result_fut.cancel()
+
+
+def new_task_id() -> str:
+    return str(uuid.uuid4())

asynclet-0.1.0/asynclet/worker.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import asyncio
+import atexit
+import concurrent.futures
+import threading
+from typing import Any, Coroutine, Optional, TypeVar
+
+T = TypeVar("T")
+
+_loop: Optional[asyncio.AbstractEventLoop] = None
+_thread: Optional[threading.Thread] = None
+_lock = threading.Lock()
+
+
+def _run_loop(loop: asyncio.AbstractEventLoop, ready: threading.Event) -> None:
+    asyncio.set_event_loop(loop)
+    ready.set()
+    loop.run_forever()
+
+
+def get_worker_loop() -> asyncio.AbstractEventLoop:
+    """Return the dedicated asyncio loop (starts the worker thread on first use)."""
+    global _loop, _thread
+    with _lock:
+        if _thread is not None and _thread.is_alive() and _loop is not None:
+            return _loop
+        ready = threading.Event()
+        loop = asyncio.new_event_loop()
+        thread = threading.Thread(
+            target=_run_loop,
+            args=(loop, ready),
+            name="asynclet-worker",
+            daemon=True,
+        )
+        thread.start()
+        if not ready.wait(timeout=30.0):
+            raise RuntimeError("asynclet worker failed to start")
+        _loop = loop
+        _thread = thread
+        return loop
+
+
+def submit_coro(coro: Coroutine[Any, Any, T]) -> concurrent.futures.Future[T]:
+    loop = get_worker_loop()
+    return asyncio.run_coroutine_threadsafe(coro, loop)
+
+
+def shutdown_worker() -> None:
+    global _loop, _thread
+    with _lock:
+        loop, _loop = _loop, None
+        th, _thread = _thread, None
+    if loop is not None and loop.is_running():
+        loop.call_soon_threadsafe(loop.stop)
+    if th is not None:
+        th.join(timeout=5.0)
+
+
+atexit.register(shutdown_worker)

asynclet-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "asynclet"
+version = "0.1.0"
+description = "Async task layer for Streamlit: background sync/async work, polling, progress, cancellation"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "asynclet contributors" }]
+keywords = ["streamlit", "async", "background", "tasks"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "asyncer>=0.0.2",
+  "janus>=1.0.0",
+]
+
+[project.optional-dependencies]
+streamlit = ["streamlit>=1.28.0"]
+scheduler = ["apscheduler>=3.10.0"]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "streamlit>=1.33.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/asynclet/asynclet"
+
+[tool.hatch.build.targets.wheel]
+packages = ["asynclet"]
+
+[tool.hatch.build.targets.sdist]
+include = ["asynclet"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]