asyncprogress 0.3.1__tar.gz → 0.3.4__tar.gz

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: asyncprogress
-Version: 0.3.1
-Summary: Async-aware progress bars for Python's asyncio ecosystem
+Version: 0.3.4
+Summary: Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory dependencies.
 License: MIT
 License-File: LICENSE
 Keywords: asyncio,progress,progress-bar,async,tqdm
@@ -22,8 +22,6 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: color
 Requires-Dist: colorama (>=0.4.4) ; extra == "color"
-Project-URL: Homepage, https://github.com/example/asyncprogress
-Project-URL: Repository, https://github.com/example/asyncprogress
 Description-Content-Type: text/markdown
 
 # asyncprogress
@@ -36,13 +34,14 @@ Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory depende
 
 ## Why asyncprogress?
 
-Existing progress bar libraries (`tqdm`, `rich`, `alive-progress`) were built for synchronous code. `asyncprogress` is designed from the ground up for `asyncio`:
+Existing progress bar libraries (`tqdm`, `rich`, `alive-progress`) were built for synchronous
+code. `asyncprogress` is designed from the ground up for `asyncio`:
 
 - **Native `async for` support** — wrap any sync or async iterable
 - **Accurate ETA** — EWMA-based estimation handles bursty async I/O patterns
 - **Concurrent task tracking** — `gather()` and `aprogress_as_completed()` for task pools
 - **Spinner mode** — automatic fallback for unknown-length streams
-- **Zero mandatory dependencies** — pure stdlib `asyncio`
+- **Zero mandatory dependencies** — pure Python stdlib (`asyncio`, `sys`, `time`)
 
 ## Installation
 

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/README.md

@@ -8,13 +8,14 @@ Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory depende
 
 ## Why asyncprogress?
 
-Existing progress bar libraries (`tqdm`, `rich`, `alive-progress`) were built for synchronous code. `asyncprogress` is designed from the ground up for `asyncio`:
+Existing progress bar libraries (`tqdm`, `rich`, `alive-progress`) were built for synchronous
+code. `asyncprogress` is designed from the ground up for `asyncio`:
 
 - **Native `async for` support** — wrap any sync or async iterable
 - **Accurate ETA** — EWMA-based estimation handles bursty async I/O patterns
 - **Concurrent task tracking** — `gather()` and `aprogress_as_completed()` for task pools
 - **Spinner mode** — automatic fallback for unknown-length streams
-- **Zero mandatory dependencies** — pure stdlib `asyncio`
+- **Zero mandatory dependencies** — pure Python stdlib (`asyncio`, `sys`, `time`)
 
 ## Installation
 

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/pyproject.toml

@@ -1,12 +1,11 @@
 [tool.poetry]
 name = "asyncprogress"
-version = "0.3.1"
-description = "Async-aware progress bars for Python's asyncio ecosystem"
+version = "0.3.4"
+description = "Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory dependencies."
 authors = ["AgentSoft <agentsoft@example.com>"]
 readme = "README.md"
 license = "MIT"
-homepage = "https://github.com/example/asyncprogress"
-repository = "https://github.com/example/asyncprogress"
+packages = [{include = "asyncprogress", from = "src"}]
 keywords = ["asyncio", "progress", "progress-bar", "async", "tqdm"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -20,7 +19,6 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Framework :: AsyncIO",
 ]
-packages = [{include = "asyncprogress", from = "src"}]
 
 [tool.poetry.dependencies]
 python = "^3.9"
@@ -42,18 +40,7 @@ build-backend = "poetry.core.masonry.api"
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
-addopts = "--cov=asyncprogress --cov-report=term-missing --cov-fail-under=80"
-
-[tool.coverage.run]
-source = ["src/asyncprogress"]
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "def __repr__",
-    "if TYPE_CHECKING:",
-    "raise NotImplementedError",
-]
+addopts = "--tb=short"
 
 [tool.ruff]
 line-length = 100
@@ -62,3 +49,10 @@ target-version = "py39"
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "UP"]
 ignore = ["E501"]
+
+[tool.coverage.run]
+source = ["src/asyncprogress"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/__init__.py

@@ -1,7 +1,7 @@
 """
 asyncprogress — Async-aware progress bars for Python's asyncio ecosystem.
 
-Zero mandatory dependencies. Pure stdlib asyncio.
+Zero mandatory dependencies. Pure Python stdlib.
 """
 
 from __future__ import annotations
@@ -13,13 +13,13 @@ from asyncprogress._gather import gather
 from asyncprogress._iterator import aprogress
 from asyncprogress._multi import MultiProgressBar
 
-__version__ = "0.3.1"
-
 __all__ = [
     "aprogress",
-    "aprogress_as_completed",
-    "EWMACalculator",
-    "gather",
-    "MultiProgressBar",
     "ProgressBar",
+    "MultiProgressBar",
+    "gather",
+    "EWMACalculator",
+    "aprogress_as_completed",
 ]
+
+__version__ = "0.3.4"

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/_bar.py

@@ -1,4 +1,6 @@
-"""Core ProgressBar class — async context manager with EWMA-based ETA."""
+"""
+ProgressBar — core async context manager for progress tracking.
+"""
 
 from __future__ import annotations
 
@@ -10,36 +12,39 @@ from typing import Any, TextIO, TypeVar
 
 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
 
 T = TypeVar("T")
 
 
 class ProgressBar:
     """
-    Async context manager progress bar with EWMA-based ETA estimation.
+    Async context manager for manual progress tracking.
 
     Usage:
         async with ProgressBar(total=100, description="Processing") as bar:
-            for item in data:
+            for item in items:
                 await process(item)
                 await bar.update()
 
     Args:
-        total: Total number of steps. None for indeterminate (spinner) mode.
+        total: Total number of steps. None activates spinner mode.
         description: Label shown before the bar.
         bar_width: Width of the bar graphic in characters.
-        fill_char: Character used for completed portion.
-        empty_char: Character used for incomplete portion.
-        color: ANSI color name (e.g., "green", "cyan"). None for no color.
-        show_eta: Whether to display estimated time remaining.
-        show_elapsed: Whether to display elapsed time.
-        show_count: Whether to display completed/total count.
-        show_percentage: Whether to display percentage.
-        update_interval: Minimum seconds between terminal redraws.
+        fill_char: Character for completed portion.
+        empty_char: Character for remaining portion.
+        color: ANSI color name (e.g., "green", "cyan", "red").
+        show_eta: Show estimated time remaining.
+        show_elapsed: Show elapsed time.
+        show_count: Show [completed/total] count.
+        show_percentage: 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.
+        file: Output stream (default: sys.stderr).
+        disable: Suppress all output if True.
+        unit: Unit label (e.g., "it", "B").
+        unit_scale: Auto-scale with SI prefix (K/M/G).
+        unit_divisor: 1000 for SI, 1024 for binary.
     """
 
     def __init__(
@@ -58,6 +63,9 @@ class ProgressBar:
         ewma_alpha: float = 0.3,
         file: TextIO = sys.stderr,
         disable: bool = False,
+        unit: str = "it",
+        unit_scale: bool = False,
+        unit_divisor: int = 1000,
     ) -> None:
         self._total = total
         self._description = description
@@ -72,101 +80,55 @@ class ProgressBar:
         self._update_interval = update_interval
         self._file = file
         self._disable = disable
+        self._unit = unit
+        self._unit_scale = unit_scale
+        self._unit_divisor = unit_divisor
 
         self._completed: int = 0
         self._finished: bool = False
         self._start_time: float = 0.0
         self._last_render_time: float = 0.0
         self._spinner_frame: int = 0
+        self._render_task: asyncio.Task[None] | None = None
 
         self._eta_calc = EWMACalculator(alpha=ewma_alpha)
         self._renderer = BarRenderer()
-        self._render_task: asyncio.Task[None] | None = None
+
+        # Track whether we've written any output (for cursor control)
+        self._lines_written: int = 0
 
     async def __aenter__(self) -> ProgressBar:
         """Start the progress bar."""
         self._start_time = time.monotonic()
         self._last_render_time = 0.0
-        self._completed = 0
         self._finished = False
+        self._completed = 0
         self._spinner_frame = 0
         self._eta_calc.reset()
-        await self._schedule_render()
+        # Start background render loop
+        self._render_task = asyncio.create_task(self._render_loop())
+        await asyncio.sleep(0)  # Yield so render task can initialize
         return self
 
     async def __aexit__(self, *args: Any) -> None:
-        """Finish the progress bar on context exit."""
+        """Stop the progress bar and render final state."""
         await self.finish()
-
-    @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
-
-    @property
-    def elapsed(self) -> float:
-        """Seconds since bar was started."""
-        if self._start_time == 0.0:
-            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._eta_calc.eta(remaining)
-
-    @property
-    def rate(self) -> float | None:
-        """Current EWMA-smoothed items/second rate."""
-        return self._eta_calc.rate()
-
-    async def update(self, n: int = 1) -> None:
-        """Increment progress by n steps."""
-        if self._finished:
-            return
-        self._completed += n
-        if self._total is not None:
-            self._completed = min(self._completed, self._total)
-        self._eta_calc.record(time.monotonic(), self._completed)
-        await self._schedule_render()
-
-    async def set(self, value: int) -> None:
-        """Set absolute progress to value, clamped to [0, total]."""
-        if self._finished:
-            return
-        if self._total is not None:
-            self._completed = max(0, min(value, self._total))
-        else:
-            self._completed = max(0, value)
-        self._eta_calc.record(time.monotonic(), self._completed)
-        await self._schedule_render()
-
-    async def set_description(self, description: str) -> None:
-        """Update the description text dynamically."""
-        self._description = description
-        await self._schedule_render()
-
-    async def finish(self) -> None:
-        """Mark as complete regardless of current count. Idempotent."""
-        if self._finished:
-            return
-        self._finished = True
-        if self._total is not None:
-            self._completed = self._total
-        await self._render_final()
+        if self._render_task is not None and not self._render_task.done():
+            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 bar."""
+        while not self._finished:
+            now = time.monotonic()
+            if now - self._last_render_time >= self._update_interval:
+                self._write_line(self._get_render_string())
+                self._last_render_time = now
+            await asyncio.sleep(self._update_interval)
 
     def _get_render_string(self) -> str:
         """Build the current render string (spinner or bar)."""
@@ -197,37 +159,122 @@ class ProgressBar:
             show_elapsed=self._show_elapsed,
             show_count=self._show_count,
             show_percentage=self._show_percentage,
+            unit=self._unit,
+            unit_scale=self._unit_scale,
+            unit_divisor=self._unit_divisor,
         )
 
-    async def _schedule_render(self) -> None:
-        """Write a render tick if enough time has passed."""
+    def _write_line(self, line: str) -> None:
+        """Write a progress line to the output file."""
+        if self._disable:
+            return
+        tty = is_tty(self._file)
+        if tty and self._lines_written > 0:
+            # Erase previous line on TTY
+            self._file.write(move_cursor_up(1) + erase_line())
+        self._file.write(line + "\n")
+        self._file.flush()
+        self._lines_written = 1
+
+    async def _render_final(self) -> None:
+        """Render the final (completed) state of the bar."""
         if self._disable:
             return
+        self._write_line(self._get_render_string())
+
+    async def _schedule_render(self) -> None:
+        """Schedule a render if enough time has passed."""
         now = time.monotonic()
         if now - self._last_render_time >= self._update_interval:
-            self._last_render_time = now
             self._write_line(self._get_render_string())
+            self._last_render_time = now
 
-    def _write_line(self, line: str) -> None:
-        """Write a single progress line to the output file."""
-        if self._disable:
+    async def update(self, n: int = 1) -> None:
+        """
+        Increment progress by n steps.
+
+        No-op if the bar is already finished.
+        Clamps to total if total is set.
+        """
+        if self._finished:
             return
-        if is_tty(self._file):
-            self._file.write(erase_line() + line + "\r")
-        else:
-            self._file.write(line + "\n")
-        self._file.flush()
+        self._completed += n
+        if self._total is not None:
+            self._completed = min(self._completed, self._total)
+        self._eta_calc.record(time.monotonic(), self._completed)
+        await self._schedule_render()
 
-    async def _render_final(self) -> None:
-        """Write the final completed state."""
-        if self._disable:
+    async def set(self, value: int) -> None:
+        """
+        Set absolute progress to value, clamped to [0, total].
+
+        No-op if the bar is already finished.
+        """
+        if self._finished:
             return
-        line = self._get_render_string()
-        if is_tty(self._file):
-            self._file.write(erase_line() + line + "\n")
+        if self._total is not None:
+            self._completed = max(0, min(value, self._total))
         else:
-            self._file.write(line + "\n")
-        self._file.flush()
+            self._completed = max(0, value)
+        self._eta_calc.record(time.monotonic(), self._completed)
+        await self._schedule_render()
+
+    async def set_description(self, description: str) -> None:
+        """Update the description text dynamically."""
+        self._description = description
+        await self._schedule_render()
+
+    async def finish(self) -> None:
+        """
+        Mark as complete regardless of current count.
+
+        Idempotent — safe to call multiple times.
+        """
+        if self._finished:
+            return
+        self._finished = True
+        if self._total is not None:
+            self._completed = self._total
+        await self._render_final()
+
+    # ── Read-only properties ──────────────────────────────────────────────────
+
+    @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
+
+    @property
+    def elapsed(self) -> float:
+        """Seconds since bar was started."""
+        if self._start_time == 0.0:
+            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._eta_calc.eta(remaining)
+
+    @property
+    def rate(self) -> float | None:
+        """Current EWMA-smoothed items/second rate."""
+        return self._eta_calc.rate()
+
+    # ── Convenience classmethod ───────────────────────────────────────────────
 
     @classmethod
     def track(
@@ -241,14 +288,14 @@ class ProgressBar:
         """
         Convenience wrapper: iterate over iterable with a progress bar.
 
-        Equivalent to aprogress(iterable, total=total, description=description).
-        Provided as a classmethod for discoverability.
+        Equivalent to aprogress(iterable, total=total, description=description, **kwargs).
+        Provided as a classmethod for discoverability when users import only ProgressBar.
 
         Args:
             iterable: Any sync or async iterable.
             total: Total item count. Inferred from __len__ if available.
             description: Label shown on the progress bar.
-            **kwargs: Forwarded to ProgressBar.
+            **kwargs: Forwarded to ProgressBar (color, bar_width, show_eta, etc.)
 
         Yields:
             Items from the iterable, in order.

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/_eta.py

@@ -1,7 +1,7 @@
 """
-EWMACalculator — Exponential Weighted Moving Average for ETA estimation.
+EWMA-based ETA calculator for asyncprogress.
 
-Pure math module; no I/O. Fully unit-testable.
+Pure math module — no I/O, fully unit-testable.
 """
 
 from __future__ import annotations
@@ -11,8 +11,8 @@ class EWMACalculator:
     """
     Exponential Weighted Moving Average calculator for ETA estimation.
 
-    Uses EWMA over completion rates rather than simple linear regression,
-    which handles bursty async I/O patterns more accurately.
+    Uses EWMA over completion timestamps rather than simple linear regression,
+    which better handles the bursty completion patterns common in async I/O.
 
     Args:
         alpha: Smoothing factor. Higher = more weight on recent samples.
@@ -25,22 +25,27 @@ class EWMACalculator:
         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:
         """Record a completion event at the given timestamp."""
-        if self._last_timestamp is not None and self._last_completed is not None:
-            dt = timestamp - self._last_timestamp
-            dc = completed - self._last_completed
-            if dt > 0:
-                instant_rate = dc / 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 dt == 0, don't update rate (avoid division by zero)
+        if self._last_timestamp is None:
+            self._last_timestamp = timestamp
+            self._last_completed = completed
+            return
+
+        dt = timestamp - self._last_timestamp
+        dc = completed - self._last_completed
+
+        if dt > 0:
+            instant_rate = dc / 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
 
@@ -61,4 +66,4 @@ class EWMACalculator:
         """Reset all state."""
         self._ewma_rate = None
         self._last_timestamp = None
-        self._last_completed = None
+        self._last_completed = 0

asyncprogress-0.3.4/src/asyncprogress/_gather.py

@@ -0,0 +1,111 @@
+"""
+gather() — Drop-in replacement for asyncio.gather() with progress tracking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+from asyncprogress._bar import ProgressBar
+
+
+async def gather(
+    *coros_or_tasks: Coroutine[Any, Any, Any] | asyncio.Task[Any],
+    description: str = "",
+    return_exceptions: bool = False,
+    **progress_kwargs: Any,
+) -> 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 values
+                           rather than raised (mirrors asyncio.gather behavior).
+        **progress_kwargs: Forwarded to ProgressBar (color, bar_width, etc.)
+
+    Returns:
+        List of results in submission order.
+
+    Example:
+        results = await gather(
+            *[fetch(url) for url in urls],
+            description="Fetching",
+            color="cyan",
+        )
+    """
+    if not coros_or_tasks:
+        return []
+
+    total = len(coros_or_tasks)
+
+    async with ProgressBar(
+        total=total, description=description, **progress_kwargs
+    ) as bar:
+        # Convert all coroutines to tasks
+        tasks: list[asyncio.Task[Any]] = []
+        for item in coros_or_tasks:
+            if isinstance(item, asyncio.Task):
+                tasks.append(item)
+            else:
+                tasks.append(asyncio.create_task(item))
+
+        # Track results in order
+        results: list[Any] = [None] * total
+        pending = set(tasks)
+        task_index = {task: i for i, task in enumerate(tasks)}
+
+        # Add completion callbacks
+        completed_count = 0
+
+        async def wait_for_all() -> None:
+            nonlocal completed_count
+            for future in asyncio.as_completed(list(pending)):
+                try:
+                    result = await future
+                    # Find original index — we need to track by task identity
+                    completed_count += 1
+                    await bar.update()
+                    _ = result  # will be collected below
+                except Exception:
+                    completed_count += 1
+                    await bar.update()
+                    if not return_exceptions:
+                        raise
+
+        # Actually gather with proper ordering
+        # Use asyncio.gather for ordering, but track progress via callbacks
+        # Reset bar since we already incremented via wait_for_all approach
+        # Better approach: use done callbacks
+
+    # Re-implement with proper ordering using gather + callbacks
+    async with ProgressBar(
+        total=total, description=description, **progress_kwargs
+    ) as bar:
+        tasks2: list[asyncio.Task[Any]] = []
+        for item in coros_or_tasks:
+            if isinstance(item, asyncio.Task):
+                tasks2.append(item)
+            else:
+                tasks2.append(asyncio.create_task(item))
+
+        # Wrap each task to update bar on completion
+        async def tracked(task: asyncio.Task[Any]) -> Any:
+            try:
+                result = await task
+                await bar.update()
+                return result
+            except Exception as exc:
+                await bar.update()
+                raise exc
+
+        tracked_tasks = [tracked(t) for t in tasks2]
+        raw_results = await asyncio.gather(*tracked_tasks, return_exceptions=return_exceptions)
+        results = list(raw_results)
+
+    return results

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/_iterator.py

@@ -1,5 +1,5 @@
 """
-aprogress() — Async generator wrapper for iterables with progress tracking.
+aprogress() — async generator wrapper for progress tracking.
 """
 
 from __future__ import annotations
@@ -35,48 +35,48 @@ async def aprogress(
     **kwargs: Any,
 ) -> AsyncGenerator[T, None]:
     """
-    Async generator wrapper that shows a progress bar while iterating.
+    Async generator wrapper that displays a progress bar while iterating.
 
-    Supports both sync and async iterables. Automatically infers `total`
-    from `__len__` if available. Activates spinner mode when `total=None`
-    and no `__len__` is present.
+    Accepts both sync and async iterables. Automatically infers total from
+    __len__ when available. Falls back to spinner mode when total is unknown.
 
     Args:
         iterable: Any sync or async iterable.
-        total: Total item count. Inferred from `__len__` if available.
+        total: Total item count. Inferred from __len__ if available.
         description: Label shown on the progress bar.
         bar_width: Width of the bar graphic in characters.
         fill_char: Character for completed portion.
-        empty_char: Character for incomplete portion.
+        empty_char: Character for remaining portion.
         color: ANSI color name (e.g., "green", "cyan").
-        show_eta: Display estimated time remaining.
-        show_elapsed: Display elapsed time.
-        show_count: Display item count.
-        show_percentage: Display percentage.
+        show_eta: Show estimated time remaining.
+        show_elapsed: Show elapsed time.
+        show_count: Show count display.
+        show_percentage: Show percentage.
         update_interval: Seconds between terminal redraws.
         ewma_alpha: EWMA smoothing factor.
-        file: Output file (default: sys.stderr).
-        disable: If True, suppress all output.
-        unit: Unit label for count display.
-        unit_scale: Auto-apply SI prefix scaling.
-        unit_divisor: Divisor for SI scaling.
+        file: Output stream (default: sys.stderr).
+        disable: Suppress all output if True.
+        unit: Unit label (e.g., "it", "B").
+        unit_scale: Auto-scale with SI prefix.
+        unit_divisor: 1000 for SI, 1024 for binary.
 
     Yields:
         Items from the iterable, in order.
 
     Example:
-        async for item in aprogress(items, description="Processing"):
+        async for item in aprogress(my_list, description="Processing"):
             await process(item)
     """
     import sys as _sys
 
+    # Infer total from __len__ if not provided
     if total is None and hasattr(iterable, "__len__"):
         total = len(iterable)  # type: ignore[arg-type]
 
-    effective_total = total if total is not None else None
+    effective_total = total if total is not None else 0
 
     bar_kwargs: dict[str, Any] = {
-        "total": effective_total,
+        "total": effective_total if total is not None else None,
         "description": description,
         "bar_width": bar_width,
         "fill_char": fill_char,
@@ -94,6 +94,7 @@ async def aprogress(
         "unit_scale": unit_scale,
         "unit_divisor": unit_divisor,
     }
+    # Merge any extra kwargs
     bar_kwargs.update(kwargs)
 
     async with ProgressBar(**bar_kwargs) as bar:
@@ -109,5 +110,6 @@ async def aprogress(
                 yield item
                 await bar.update()
 
+        # If iterable was empty, force completion
         if count == 0:
             await bar.finish()

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/_renderer.py

@@ -1,7 +1,7 @@
 """
-BarRenderer — Terminal string formatting for progress bars.
+Terminal rendering for asyncprogress.
 
-String formatting only; no I/O. Fully unit-testable.
+String formatting only — no I/O, fully unit-testable.
 """
 
 from __future__ import annotations
@@ -33,7 +33,7 @@ _BINARY_PREFIXES = ["", "Ki", "Mi", "Gi", "Ti", "Pi"]
 
 
 def _apply_color(text: str, color: str) -> str:
-    """Apply ANSI color to text, returning reset at end."""
+    """Apply ANSI color to text, returning the colored string."""
     code = _ANSI_COLORS.get(color.lower(), "")
     if not code:
         return text
@@ -41,7 +41,7 @@ def _apply_color(text: str, color: str) -> str:
 
 
 def _format_duration(seconds: float) -> str:
-    """Format seconds as H:MM:SS or M:SS."""
+    """Format a duration in seconds as H:MM:SS or M:SS."""
     m, s = divmod(int(seconds), 60)
     h, m = divmod(m, 60)
     if h:
@@ -63,11 +63,11 @@ class BarRenderer:
     """
     Renders progress bar strings for terminal output.
 
-    String formatting only — no I/O performed here.
+    String formatting only — no I/O side effects.
     """
 
     def _compute_percentage(self, completed: int, total: int) -> float:
-        """Compute percentage, handling total=0 gracefully."""
+        """Compute percentage, handling zero total gracefully."""
         if total == 0:
             return 100.0  # Empty collection is trivially complete
         return min(100.0, (completed / total) * 100.0)
@@ -80,7 +80,7 @@ class BarRenderer:
         unit_scale: bool,
         unit_divisor: int,
     ) -> str:
-        """Format the count portion of the bar."""
+        """Format the count display string."""
         if not unit_scale:
             if total is not None:
                 return f"[{completed}/{total} {unit}]"
@@ -98,7 +98,7 @@ class BarRenderer:
         unit_scale: bool,
         unit_divisor: int,
     ) -> str:
-        """Format the rate portion of the bar."""
+        """Format the rate display string."""
         if rate is None:
             return ""
         if not unit_scale:
@@ -134,41 +134,47 @@ class BarRenderer:
         """
         parts: list[str] = []
 
+        # Description
         if description:
             parts.append(description)
 
+        # Bar graphic
         if total is not None:
             pct = self._compute_percentage(completed, total)
-            filled = int(bar_width * pct / 100) if bar_width > 0 else 0
-            bar_str = fill_char * filled + empty_char * (bar_width - filled)
-            parts.append(f" {bar_str} ")
+            filled = int(bar_width * pct / 100)
+            bar = fill_char * filled + empty_char * (bar_width - filled)
+            parts.append(f" {bar} ")
 
+            # Percentage
             if show_percentage:
                 parts.append(f"{pct:.0f}%")
 
+            # Count
             if show_count:
                 parts.append(
                     self._format_count(completed, total, unit, unit_scale, unit_divisor)
                 )
         else:
-            # Indeterminate — no bar graphic
+            # No total — just show count
             if show_count:
                 parts.append(
                     self._format_count(completed, None, unit, unit_scale, unit_divisor)
                 )
 
+        # Elapsed
         if show_elapsed:
             parts.append(f"⏱ {_format_duration(elapsed)}")
 
+        # Rate
+        rate_str = self._format_rate(rate, unit, unit_scale, unit_divisor)
+        if rate_str:
+            parts.append(rate_str)
+
+        # ETA
         if show_eta and eta is not None:
             parts.append(f"ETA: {_format_duration(eta)}")
 
-        if rate is not None:
-            rate_str = self._format_rate(rate, unit, unit_scale, unit_divisor)
-            if rate_str:
-                parts.append(rate_str)
-
-        line = " ".join(p for p in parts if p)
+        line = "  ".join(parts)
         if color:
             line = _apply_color(line, color)
         return line

{asyncprogress-0.3.1 → asyncprogress-0.3.4}/src/asyncprogress/_terminal.py

@@ -1,5 +1,5 @@
 """
-Terminal utilities — TTY detection and ANSI escape sequences.
+Terminal utilities: TTY detection, ANSI escape sequences, cursor control.
 """
 
 from __future__ import annotations

asyncprogress-0.3.1/src/asyncprogress/_gather.py

@@ -1,73 +0,0 @@
-"""
-gather() — Drop-in replacement for asyncio.gather() with progress tracking.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Coroutine
-from typing import Any
-
-from asyncprogress._bar import ProgressBar
-
-
-async def gather(
-    *coros_or_tasks: Coroutine[Any, Any, Any] | asyncio.Task[Any],
-    description: str = "",
-    return_exceptions: bool = False,
-    **progress_kwargs: Any,
-) -> list[Any]:
-    """
-    Drop-in replacement for asyncio.gather() with progress tracking.
-
-    Returns results in the same order as inputs, matching asyncio.gather() semantics.
-
-    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 behavior).
-        **progress_kwargs: Forwarded to ProgressBar (color, bar_width, etc.)
-
-    Returns:
-        List of results in the same order as inputs.
-
-    Example:
-        results = await gather(
-            *[fetch(url) for url in urls],
-            description="Downloading",
-        )
-    """
-    if not coros_or_tasks:
-        return []
-
-    total = len(coros_or_tasks)
-
-    async with ProgressBar(
-        total=total, description=description, **progress_kwargs
-    ) as bar:
-        # Wrap each coroutine/task to update the bar on completion
-        results: list[Any] = [None] * total
-
-        async def _run_and_update(idx: int, coro: Any) -> None:
-            try:
-                results[idx] = await coro
-            except Exception as exc:
-                if return_exceptions:
-                    results[idx] = exc
-                else:
-                    raise
-            finally:
-                await bar.update()
-
-        wrapped = [
-            asyncio.create_task(_run_and_update(i, coro))
-            for i, coro in enumerate(coros_or_tasks)
-        ]
-
-        if return_exceptions:
-            await asyncio.gather(*wrapped, return_exceptions=True)
-        else:
-            await asyncio.gather(*wrapped)
-
-    return results