python-async-aware-progress-bar 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

asyncprogress/__init__.py

@@ -1,25 +1,30 @@
 """
 asyncprogress — Async-aware progress bar for Python asyncio applications.
 
-Provides:
-    - aprogress: async generator wrapper for iterables
-    - ProgressBar: manual async context manager
-    - MultiProgressBar: concurrent progress bars manager
-    - gather: drop-in asyncio.gather replacement with progress tracking
-    - EWMACalculator: exponential weighted moving average ETA engine
+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.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "aprogress",
     "ProgressBar",
     "MultiProgressBar",
     "gather",
     "EWMACalculator",
+    "aprogress_as_completed",
 ]

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

asyncprogress/_bar.py

@@ -1,4 +1,4 @@
-"""Core ProgressBar class: async context manager with update scheduling."""
+"""Core ProgressBar class — async context manager with state machine."""
 
 from __future__ import annotations
 
@@ -9,28 +9,21 @@ from typing import TextIO
 
 from asyncprogress._eta import EWMACalculator
 from asyncprogress._renderer import BarRenderer
-from asyncprogress._terminal import ERASE_LINE, is_tty
+from asyncprogress._terminal import erase_line, is_tty, move_cursor_up
 
 
 class ProgressBar:
     """
-    Async context manager progress bar with EWMA-based ETA estimation.
-
-    Args:
-        total: Total number of items, or None for indeterminate.
-        description: Label shown before the bar.
-        bar_width: Width of the bar graphic in characters.
-        fill_char: Character for completed portion.
-        empty_char: Character for remaining portion.
-        color: ANSI color name (e.g., "green", "cyan") 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 (0 < alpha ≤ 1).
-        file: Output file (default: sys.stderr).
-        disable: If True, suppress all output.
+    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__(
@@ -49,156 +42,176 @@ class ProgressBar:
         ewma_alpha: float = 0.3,
         file: TextIO = sys.stderr,
         disable: bool = False,
-        _manager: object = None,
     ) -> 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._manager = _manager
+        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 = 0.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_render_time: float = 0.0
-        self._is_tty = is_tty(file)
+        self._last_line_count: int = 0
 
-    async def __aenter__(self) -> "ProgressBar":
+        # Whether this bar is managed by a MultiProgressBar
+        self._managed: bool = False
+
+    async def __aenter__(self) -> ProgressBar:
         self._start_time = time.monotonic()
-        self._completed = 0
-        self._finished = False
-        self._ewma.reset()
-        if not self.disable and self._manager is None:
-            self._render_task = asyncio.get_event_loop().create_task(
-                self._render_loop()
-            )
+        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._render()
-                await asyncio.sleep(self.update_interval)
-            # Final render after finish
-            self._render(final=True)
+                self._write_frame()
+                await asyncio.sleep(self._update_interval)
         except asyncio.CancelledError:
-            self._render(final=True)
+            pass
 
-    def _render(self, final: bool = False) -> None:
-        """Render the progress bar to the output file."""
-        if self.disable:
+    def _write_frame(self) -> None:
+        """Write a single frame to the output file."""
+        if self._disable:
             return
-        line = self._renderer.render(
-            description=self.description,
+        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,
+            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,
+            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,
         )
-        if self._is_tty:
-            self.file.write(f"{ERASE_LINE}{line}")
-            if final:
-                self.file.write("\n")
-        else:
-            # Non-TTY: print milestone percentages
-            if self.total and self.total > 0:
-                pct = int(self._completed / self.total * 100)
-                milestones = [10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 100]
-                if pct in milestones or final:
-                    self.file.write(line + "\n")
-            elif final:
-                self.file.write(line + "\n")
-        self.file.flush()
+
+    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.
+            n: Number of steps to increment. Default is 1.
         """
         self._completed += n
         now = time.monotonic()
         self._ewma.record(now, self._completed)
-        if self._manager is not None:
-            # Managed bars delegate rendering to the manager
-            return
-        # Throttled direct render for non-managed bars without render loop
-        # (render loop handles periodic rendering; this is a no-op here)
+
+        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.
+            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 string.
+            description: New description label.
         """
-        self.description = description
+        self._description = description
 
     async def finish(self) -> None:
         """Mark as complete regardless of current count."""
         if self._finished:
             return
         self._finished = True
-        if self._render_task is not None:
-            self._render_task.cancel()
-            try:
-                await self._render_task
-            except asyncio.CancelledError:
-                pass
-            self._render_task = None
-        if not self.disable and self._manager is None:
-            self._render(final=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 == 0.0:
+        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:
+        if self._total is None:
             return None
-        remaining = max(0, self.total - self._completed)
+        remaining = self._total - self._completed
         return self._ewma.eta(remaining)
 
     @property
@@ -206,7 +219,17 @@ class ProgressBar:
         """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 completed items."""
+        """Number of steps completed so far."""
         return self._completed
+
+    @property
+    def total(self) -> int | None:
+        """Total steps, or None if indeterminate."""
+        return self._total

asyncprogress/_eta.py

@@ -1,27 +1,25 @@
-"""EWMA-based ETA calculator for asyncprogress."""
+"""Exponential Weighted Moving Average (EWMA) calculator for ETA estimation."""
 
 from __future__ import annotations
 
 
 class EWMACalculator:
     """
-    Exponential Weighted Moving Average calculator for ETA estimation.
-
-    Uses EWMA over completion timestamps to produce smooth rate estimates
-    that handle bursty async I/O patterns better than simple linear regression.
+    Calculates smoothed rate and ETA using Exponential Weighted Moving Average.
 
     Args:
-        alpha: Smoothing factor. Higher values weight recent samples more.
-               Recommended range: 0.1 (smooth) to 0.5 (reactive).
+        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._alpha = alpha
         self._ewma_rate: float | None = None
         self._last_timestamp: float | None = None
-        self._last_completed: int | None = None
+        self._last_completed: int = 0
 
     def record(self, timestamp: float, completed: int) -> None:
         """
@@ -31,47 +29,56 @@ class EWMACalculator:
             timestamp: Current time in seconds (e.g., from time.monotonic()).
             completed: Total number of items completed so far.
         """
-        if self._last_timestamp is not None and self._last_completed is not None:
-            dt = timestamp - self._last_timestamp
-            delta = completed - self._last_completed
-            if dt > 0 and delta >= 0:
-                instant_rate = delta / 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
-                    )
+        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:
         """
-        Return smoothed items/second rate, or None if insufficient data.
-
-        Returns:
-            Smoothed rate in items/second, or None.
+        Returns smoothed items/second rate, or None if insufficient data.
         """
         return self._ewma_rate
 
     def eta(self, remaining: int) -> float | None:
         """
-        Return estimated seconds to completion.
+        Returns estimated seconds to completion, or None if rate is unknown.
 
         Args:
-            remaining: Number of items remaining.
-
-        Returns:
-            Estimated seconds remaining, or None if rate is unknown.
+            remaining: Number of items remaining to complete.
         """
-        r = self._ewma_rate
-        if r is None or r <= 0:
+        if self._ewma_rate is None or self._ewma_rate <= 0:
             return None
-        return remaining / r
+        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 = None
+        self._last_completed = 0