python-async-aware-progress-bar 0.1.0__tar.gz → 0.2.0__tar.gz

python_async_aware_progress_bar-0.2.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: python-async-aware-progress-bar
+Version: 0.2.0
+Summary: Async-aware progress bar for Python asyncio applications
+License: MIT
+License-File: LICENSE
+Keywords: async,asyncio,progress,progress-bar,cli
+Author: AgentSoft
+Author-email: agentsoft@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Provides-Extra: color
+Requires-Dist: colorama (>=0.4.4) ; extra == "color"
+Description-Content-Type: text/markdown
+
+# asyncprogress
+
+An async-aware progress bar library for Python's asyncio ecosystem.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **`async for` support**: Wrap async generators and sync iterables naturally
+- **Task pool tracking**: Drop-in replacement for `asyncio.gather()` with progress
+- **Manual progress bars**: Async context manager for complex workflows
+- **Multiple concurrent bars**: Track several operations simultaneously
+- **Accurate ETA**: Exponential Weighted Moving Average (EWMA) for burst-pattern async I/O
+- **Spinner mode**: Animated spinner for indeterminate progress
+- **Zero dependencies**: Pure Python stdlib only (optional `colorama` for Windows colors)
+
+## Installation
+
+
+
+```bash
+pip install python-async-aware-progress-bar
+```

python_async_aware_progress_bar-0.2.0/README.md

@@ -0,0 +1,24 @@
+# asyncprogress
+
+An async-aware progress bar library for Python's asyncio ecosystem.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **`async for` support**: Wrap async generators and sync iterables naturally
+- **Task pool tracking**: Drop-in replacement for `asyncio.gather()` with progress
+- **Manual progress bars**: Async context manager for complex workflows
+- **Multiple concurrent bars**: Track several operations simultaneously
+- **Accurate ETA**: Exponential Weighted Moving Average (EWMA) for burst-pattern async I/O
+- **Spinner mode**: Animated spinner for indeterminate progress
+- **Zero dependencies**: Pure Python stdlib only (optional `colorama` for Windows colors)
+
+## Installation
+
+
+
+```bash
+pip install python-async-aware-progress-bar
+```

{python_async_aware_progress_bar-0.1.0 → python_async_aware_progress_bar-0.2.0}/pyproject.toml

@@ -1,15 +1,14 @@
 [tool.poetry]
 name = "python-async-aware-progress-bar"
-version = "0.1.0"
+version = "0.2.0"
 description = "Async-aware progress bar for Python asyncio applications"
 authors = ["AgentSoft <agentsoft@example.com>"]
 readme = "README.md"
 license = "MIT"
 packages = [{include = "asyncprogress", from = "src"}]
-keywords = ["asyncio", "progress", "progress-bar", "async", "tqdm"]
+keywords = ["async", "asyncio", "progress", "progress-bar", "cli"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Framework :: AsyncIO",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -17,8 +16,9 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: Utilities",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Terminals",
+    "Framework :: AsyncIO",
 ]
 
 [tool.poetry.dependencies]
@@ -41,21 +41,21 @@ build-backend = "poetry.core.masonry.api"
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
-addopts = "--cov=asyncprogress --cov-report=term-missing --cov-report=xml"
+addopts = "--cov=asyncprogress --cov-report=term-missing --cov-fail-under=80"
 
 [tool.ruff]
 target-version = "py39"
-line-length = 88
-src = ["src"]
+line-length = 100
 
 [tool.ruff.lint]
-select = ["E", "F", "UP", "I", "W"]
-ignore = []
+select = ["E", "F", "UP", "I"]
+ignore = ["E501"]
 
 [tool.coverage.run]
 source = ["src/asyncprogress"]
-branch = true
 
 [tool.coverage.report]
-show_missing = true
-skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]

python_async_aware_progress_bar-0.2.0/src/asyncprogress/__init__.py

@@ -0,0 +1,30 @@
+"""
+asyncprogress — Async-aware progress bar for Python asyncio applications.
+
+Public API:
+    aprogress: Async generator wrapper for iterables
+    ProgressBar: Manual async context manager progress bar
+    MultiProgressBar: Concurrent progress bars manager
+    gather: Drop-in replacement for asyncio.gather() with progress
+    EWMACalculator: Exponential weighted moving average ETA calculator
+    aprogress_as_completed: Progress-tracked as_completed wrapper
+"""
+
+from __future__ import annotations
+
+from asyncprogress._as_completed import aprogress_as_completed
+from asyncprogress._bar import ProgressBar
+from asyncprogress._eta import EWMACalculator
+from asyncprogress._gather import gather
+from asyncprogress._iterator import aprogress
+from asyncprogress._multi import MultiProgressBar
+
+__version__ = "0.2.0"
+__all__ = [
+    "aprogress",
+    "ProgressBar",
+    "MultiProgressBar",
+    "gather",
+    "EWMACalculator",
+    "aprogress_as_completed",
+]

python_async_aware_progress_bar-0.2.0/src/asyncprogress/_as_completed.py

@@ -0,0 +1,93 @@
+"""aprogress_as_completed() — progress-tracked asyncio.as_completed wrapper."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import AsyncIterator, Coroutine
+from typing import Any, TextIO, TypeVar
+
+from asyncprogress._bar import ProgressBar
+
+T = TypeVar("T")
+
+
+async def aprogress_as_completed(
+    coros: list[Coroutine[Any, Any, T]],
+    *,
+    description: str = "",
+    return_exceptions: bool = False,
+    bar_width: int = 40,
+    fill_char: str = "█",
+    empty_char: str = "░",
+    color: str | None = None,
+    show_eta: bool = True,
+    show_elapsed: bool = True,
+    show_count: bool = True,
+    show_percentage: bool = True,
+    update_interval: float = 0.1,
+    ewma_alpha: float = 0.3,
+    file: TextIO = sys.stderr,
+    disable: bool = False,
+) -> AsyncIterator[T]:
+    """
+    Async generator that yields results as coroutines complete, with a progress bar.
+
+    Drop-in replacement for ``asyncio.as_completed()`` iteration patterns.
+
+    Args:
+        coros: List of coroutines to run concurrently.
+        description: Label shown on the progress bar.
+        return_exceptions: If True, exceptions are yielded as values
+                           rather than raised.
+        bar_width: Width of the bar graphic.
+        fill_char: Character for completed portion.
+        empty_char: Character for remaining portion.
+        color: ANSI color name, or None.
+        show_eta: Whether to show ETA.
+        show_elapsed: Whether to show elapsed time.
+        show_count: Whether to show item count.
+        show_percentage: Whether to show percentage.
+        update_interval: Seconds between terminal redraws.
+        ewma_alpha: EWMA smoothing factor.
+        file: Output file. Defaults to sys.stderr.
+        disable: If True, suppress all output.
+
+    Yields:
+        Results in completion order (not submission order).
+
+    Example:
+        async for result in aprogress_as_completed(coros, description="Fetching"):
+            process(result)
+    """
+    if not coros:
+        return
+
+    total = len(coros)
+    async with ProgressBar(
+        total=total,
+        description=description,
+        bar_width=bar_width,
+        fill_char=fill_char,
+        empty_char=empty_char,
+        color=color,
+        show_eta=show_eta,
+        show_elapsed=show_elapsed,
+        show_count=show_count,
+        show_percentage=show_percentage,
+        update_interval=update_interval,
+        ewma_alpha=ewma_alpha,
+        file=file,
+        disable=disable,
+    ) as bar:
+        for future in asyncio.as_completed(coros):
+            try:
+                result = await future
+                await bar.update()
+                yield result
+            except Exception as exc:
+                await bar.update()
+                if return_exceptions:
+                    yield exc  # type: ignore[misc]
+                else:
+                    raise

python_async_aware_progress_bar-0.2.0/src/asyncprogress/_bar.py

@@ -0,0 +1,235 @@
+"""Core ProgressBar class — async context manager with state machine."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+from typing import TextIO
+
+from asyncprogress._eta import EWMACalculator
+from asyncprogress._renderer import BarRenderer
+from asyncprogress._terminal import erase_line, is_tty, move_cursor_up
+
+
+class ProgressBar:
+    """
+    Async context manager progress bar.
+
+    Tracks progress of async operations and renders a live progress bar
+    to the terminal (or any file-like object).
+
+    Example:
+        async with ProgressBar(total=100, description="Processing") as bar:
+            for item in items:
+                await process(item)
+                await bar.update()
+    """
+
+    def __init__(
+        self,
+        total: int | None = None,
+        description: str = "",
+        bar_width: int = 40,
+        fill_char: str = "█",
+        empty_char: str = "░",
+        color: str | None = None,
+        show_eta: bool = True,
+        show_elapsed: bool = True,
+        show_count: bool = True,
+        show_percentage: bool = True,
+        update_interval: float = 0.1,
+        ewma_alpha: float = 0.3,
+        file: TextIO = sys.stderr,
+        disable: bool = False,
+    ) -> None:
+        self._total = total
+        self._description = description
+        self._bar_width = bar_width
+        self._fill_char = fill_char
+        self._empty_char = empty_char
+        self._color = color
+        self._show_eta = show_eta
+        self._show_elapsed = show_elapsed
+        self._show_count = show_count
+        self._show_percentage = show_percentage
+        self._update_interval = update_interval
+        self._file = file
+        self._disable = disable
+
+        self._completed: int = 0
+        self._start_time: float | None = None
+        self._finished: bool = False
+        self._spinner_frame: int = 0
+
+        self._ewma = EWMACalculator(alpha=ewma_alpha)
+        self._renderer = BarRenderer()
+
+        self._render_task: asyncio.Task | None = None  # type: ignore[type-arg]
+        self._last_line_count: int = 0
+
+        # Whether this bar is managed by a MultiProgressBar
+        self._managed: bool = False
+
+    async def __aenter__(self) -> ProgressBar:
+        self._start_time = time.monotonic()
+        if not self._disable and not self._managed:
+            self._render_task = asyncio.create_task(self._render_loop())
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.finish()
+        if self._render_task is not None:
+            self._render_task.cancel()
+            try:
+                await self._render_task
+            except asyncio.CancelledError:
+                pass
+            self._render_task = None
+
+    async def _render_loop(self) -> None:
+        """Background task that periodically redraws the progress bar."""
+        try:
+            while not self._finished:
+                self._write_frame()
+                await asyncio.sleep(self._update_interval)
+        except asyncio.CancelledError:
+            pass
+
+    def _write_frame(self) -> None:
+        """Write a single frame to the output file."""
+        if self._disable:
+            return
+        line = self._get_render_string()
+        self._erase_previous()
+        self._file.write(line + "\n")
+        self._file.flush()
+        self._last_line_count = 1
+
+    def _erase_previous(self) -> None:
+        """Erase previously written lines."""
+        if self._last_line_count > 0 and is_tty(self._file):
+            self._file.write(move_cursor_up(self._last_line_count))
+            self._file.write(erase_line())
+
+    def _get_render_string(self) -> str:
+        """Build the render string for the current state."""
+        if self._total is None:
+            self._spinner_frame += 1
+            return self._renderer.render_spinner(
+                description=self._description,
+                elapsed=self.elapsed,
+                completed=self._completed,
+                frame_index=self._spinner_frame,
+                rate=self.rate,
+                color=self._color,
+                show_elapsed=self._show_elapsed,
+                show_count=self._show_count,
+            )
+        return self._renderer.render(
+            description=self._description,
+            completed=self._completed,
+            total=self._total,
+            elapsed=self.elapsed,
+            eta=self.eta,
+            rate=self.rate,
+            bar_width=self._bar_width,
+            fill_char=self._fill_char,
+            empty_char=self._empty_char,
+            color=self._color,
+            show_eta=self._show_eta,
+            show_elapsed=self._show_elapsed,
+            show_count=self._show_count,
+            show_percentage=self._show_percentage,
+        )
+
+    async def _render_final(self) -> None:
+        """Write the final state of the progress bar."""
+        if self._disable:
+            return
+        line = self._get_render_string()
+        self._erase_previous()
+        self._file.write(line + "\n")
+        self._file.flush()
+        self._last_line_count = 1
+
+    async def update(self, n: int = 1) -> None:
+        """
+        Increment progress by n steps.
+
+        Args:
+            n: Number of steps to increment. Default is 1.
+        """
+        self._completed += n
+        now = time.monotonic()
+        self._ewma.record(now, self._completed)
+
+        if self._total is not None and self._completed >= self._total:
+            await self.finish()
+
+    async def set(self, value: int) -> None:
+        """
+        Set absolute progress to value.
+
+        Args:
+            value: Absolute progress value to set.
+        """
+        self._completed = value
+        now = time.monotonic()
+        self._ewma.record(now, self._completed)
+
+        if self._total is not None and self._completed >= self._total:
+            await self.finish()
+
+    async def set_description(self, description: str) -> None:
+        """
+        Update the description text dynamically.
+
+        Args:
+            description: New description label.
+        """
+        self._description = description
+
+    async def finish(self) -> None:
+        """Mark as complete regardless of current count."""
+        if self._finished:
+            return
+        self._finished = True
+        if self._total is not None:
+            self._completed = self._total
+        await self._render_final()
+
+    @property
+    def elapsed(self) -> float:
+        """Seconds since bar was started."""
+        if self._start_time is None:
+            return 0.0
+        return time.monotonic() - self._start_time
+
+    @property
+    def eta(self) -> float | None:
+        """Estimated seconds remaining, or None if unknown."""
+        if self._total is None:
+            return None
+        remaining = self._total - self._completed
+        return self._ewma.eta(remaining)
+
+    @property
+    def rate(self) -> float | None:
+        """Current EWMA-smoothed items/second rate."""
+        return self._ewma.rate()
+
+    @property
+    def description(self) -> str:
+        """The current description label for this progress bar."""
+        return self._description
+
+    @property
+    def completed(self) -> int:
+        """Number of steps completed so far."""
+        return self._completed
+
+    @property
+    def total(self) -> int | None:
+        """Total steps, or None if indeterminate."""
+        return self._total

python_async_aware_progress_bar-0.2.0/src/asyncprogress/_eta.py

@@ -0,0 +1,84 @@
+"""Exponential Weighted Moving Average (EWMA) calculator for ETA estimation."""
+
+from __future__ import annotations
+
+
+class EWMACalculator:
+    """
+    Calculates smoothed rate and ETA using Exponential Weighted Moving Average.
+
+    Args:
+        alpha: Smoothing factor between 0 and 1. Higher values give more
+               weight to recent samples. Recommended range: 0.1 (smooth)
+               to 0.5 (reactive). Default is 0.3.
+    """
+
+    def __init__(self, alpha: float = 0.3) -> None:
+        if not (0 < alpha <= 1):
+            raise ValueError(f"alpha must be in (0, 1], got {alpha}")
+        self._alpha = alpha
+        self._ewma_rate: float | None = None
+        self._last_timestamp: float | None = None
+        self._last_completed: int = 0
+
+    def record(self, timestamp: float, completed: int) -> None:
+        """
+        Record a completion event.
+
+        Args:
+            timestamp: Current time in seconds (e.g., from time.monotonic()).
+            completed: Total number of items completed so far.
+        """
+        if self._last_timestamp is None:
+            self._last_timestamp = timestamp
+            self._last_completed = completed
+            return
+
+        dt = timestamp - self._last_timestamp
+        if dt <= 0:
+            return
+
+        delta_completed = completed - self._last_completed
+        if delta_completed < 0:
+            # Reset if progress went backwards
+            self.reset()
+            self._last_timestamp = timestamp
+            self._last_completed = completed
+            return
+
+        instant_rate = delta_completed / dt
+
+        if self._ewma_rate is None:
+            self._ewma_rate = instant_rate
+        else:
+            self._ewma_rate = (
+                self._alpha * instant_rate + (1 - self._alpha) * self._ewma_rate
+            )
+
+        self._last_timestamp = timestamp
+        self._last_completed = completed
+
+    def rate(self) -> float | None:
+        """
+        Returns smoothed items/second rate, or None if insufficient data.
+        """
+        return self._ewma_rate
+
+    def eta(self, remaining: int) -> float | None:
+        """
+        Returns estimated seconds to completion, or None if rate is unknown.
+
+        Args:
+            remaining: Number of items remaining to complete.
+        """
+        if self._ewma_rate is None or self._ewma_rate <= 0:
+            return None
+        if remaining <= 0:
+            return 0.0
+        return remaining / self._ewma_rate
+
+    def reset(self) -> None:
+        """Reset all state."""
+        self._ewma_rate = None
+        self._last_timestamp = None
+        self._last_completed = 0

python_async_aware_progress_bar-0.2.0/src/asyncprogress/_gather.py

@@ -0,0 +1,112 @@
+"""gather() — drop-in replacement for asyncio.gather() with progress tracking."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Coroutine
+from typing import Any, TextIO
+
+from asyncprogress._bar import ProgressBar
+
+
+async def gather(
+    *coros_or_tasks: Coroutine[Any, Any, Any] | asyncio.Task[Any],
+    description: str = "",
+    return_exceptions: bool = False,
+    bar_width: int = 40,
+    fill_char: str = "█",
+    empty_char: str = "░",
+    color: str | None = None,
+    show_eta: bool = True,
+    show_elapsed: bool = True,
+    show_count: bool = True,
+    show_percentage: bool = True,
+    update_interval: float = 0.1,
+    ewma_alpha: float = 0.3,
+    file: TextIO = sys.stderr,
+    disable: bool = False,
+) -> list[Any]:
+    """
+    Drop-in replacement for asyncio.gather() with progress tracking.
+
+    Returns results in the same order as inputs.
+
+    Args:
+        *coros_or_tasks: Coroutines or Tasks to run concurrently.
+        description: Label shown on the progress bar.
+        return_exceptions: If True, exceptions are returned as results
+                           rather than raised (mirrors asyncio.gather).
+        bar_width: Width of the bar graphic.
+        fill_char: Character for completed portion.
+        empty_char: Character for remaining portion.
+        color: ANSI color name, or None.
+        show_eta: Whether to show ETA.
+        show_elapsed: Whether to show elapsed time.
+        show_count: Whether to show item count.
+        show_percentage: Whether to show percentage.
+        update_interval: Seconds between terminal redraws.
+        ewma_alpha: EWMA smoothing factor.
+        file: Output file. Defaults to sys.stderr.
+        disable: If True, suppress all output.
+
+    Returns:
+        List of results in the same order as inputs.
+
+    Example:
+        results = await gather(
+            *[fetch(url) for url in urls],
+            description="Downloading",
+            color="cyan",
+        )
+    """
+    if not coros_or_tasks:
+        return []
+
+    total = len(coros_or_tasks)
+    results: list[Any] = [None] * total
+    exceptions: list[BaseException | None] = [None] * total
+
+    async with ProgressBar(
+        total=total,
+        description=description,
+        bar_width=bar_width,
+        fill_char=fill_char,
+        empty_char=empty_char,
+        color=color,
+        show_eta=show_eta,
+        show_elapsed=show_elapsed,
+        show_count=show_count,
+        show_percentage=show_percentage,
+        update_interval=update_interval,
+        ewma_alpha=ewma_alpha,
+        file=file,
+        disable=disable,
+    ) as bar:
+        # Wrap each coroutine/task to capture result and update progress
+        async def _run_one(index: int, coro: Coroutine[Any, Any, Any] | asyncio.Task[Any]) -> None:
+            try:
+                result = await coro
+                results[index] = result
+            except Exception as exc:
+                exceptions[index] = exc
+            finally:
+                await bar.update()
+
+        wrapped = [_run_one(i, c) for i, c in enumerate(coros_or_tasks)]
+        await asyncio.gather(*wrapped)
+
+    # Re-raise or collect exceptions
+    if not return_exceptions:
+        for exc in exceptions:
+            if exc is not None:
+                raise exc
+
+    final: list[Any] = []
+    for i in range(total):
+        if exceptions[i] is not None and return_exceptions:
+            final.append(exceptions[i])
+        else:
+            final.append(results[i])
+
+    return final