asyncprogress 0.3.0__tar.gz → 0.3.4__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: asyncprogress
-Version: 0.3.0
-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
@@ -26,18 +26,22 @@ Description-Content-Type: text/markdown
 
 # asyncprogress
 
-Async-aware progress bars for Python's asyncio ecosystem. Zero dependencies, native `async for` support, accurate ETA with EWMA, and concurrent task tracking.
+Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory dependencies.
 
-## Features
+[![PyPI](https://img.shields.io/pypi/v/asyncprogress)](https://pypi.org/project/asyncprogress/)
+[![Python](https://img.shields.io/pypi/pyversions/asyncprogress)](https://pypi.org/project/asyncprogress/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why asyncprogress?
+
+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
-- **`async with` context manager** — manual progress tracking
-- **`gather()` replacement** — drop-in for `asyncio.gather()` with progress
-- **`aprogress_as_completed()`** — progress-tracked `as_completed` wrapper
-- **Spinner mode** — automatic for indeterminate progress
-- **EWMA-based ETA** — accurate estimates for bursty async workloads
-- **Multiple concurrent bars** — `MultiProgressBar` for parallel streams
-- **Zero mandatory dependencies** — stdlib only
+- **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 Python stdlib (`asyncio`, `sys`, `time`)
 
 ## Installation
 

asyncprogress-0.3.4/README.md

@@ -0,0 +1,26 @@
+# asyncprogress
+
+Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory dependencies.
+
+[![PyPI](https://img.shields.io/pypi/v/asyncprogress)](https://pypi.org/project/asyncprogress/)
+[![Python](https://img.shields.io/pypi/pyversions/asyncprogress)](https://pypi.org/project/asyncprogress/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why asyncprogress?
+
+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 Python stdlib (`asyncio`, `sys`, `time`)
+
+## Installation
+
+
+
+```bash
+pip install asyncprogress
+```

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

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "asyncprogress"
-version = "0.3.0"
-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"
@@ -40,7 +40,7 @@ build-backend = "poetry.core.masonry.api"
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
-addopts = "--cov=src/asyncprogress --cov-report=term-missing --cov-fail-under=80"
+addopts = "--tb=short"
 
 [tool.ruff]
 line-length = 100
@@ -52,4 +52,7 @@ ignore = ["E501"]
 
 [tool.coverage.run]
 source = ["src/asyncprogress"]
-omit = ["*/tests/*"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true

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

@@ -1,8 +1,7 @@
 """
 asyncprogress — Async-aware progress bars for Python's asyncio ecosystem.
 
-Zero dependencies, native async for support, accurate EWMA-based ETA,
-and concurrent task tracking.
+Zero mandatory dependencies. Pure Python stdlib.
 """
 
 from __future__ import annotations
@@ -23,4 +22,4 @@ __all__ = [
     "aprogress_as_completed",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.3.4"

{asyncprogress-0.3.0 → 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.0 → 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
@@ -12,7 +12,7 @@ class EWMACalculator:
     Exponential Weighted Moving Average calculator for ETA estimation.
 
     Uses EWMA over completion timestamps rather than simple linear regression,
-    which better accounts for burst patterns common in async I/O workloads.
+    which better handles the bursty completion patterns common in async I/O.
 
     Args:
         alpha: Smoothing factor. Higher = more weight on recent samples.
@@ -25,31 +25,36 @@ 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, skip this sample (same timestamp)
+        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
 
     def rate(self) -> float | None:
-        """Return smoothed items/second, or None if insufficient data."""
+        """Returns smoothed items/second, or None if insufficient data."""
         return self._ewma_rate
 
     def eta(self, remaining: int) -> float | None:
-        """Return estimated seconds to completion, or None if unknown."""
+        """Returns estimated seconds to completion, or None if unknown."""
         if remaining == 0:
             return 0.0
         r = self.rate()
@@ -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.0 → 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.0 → asyncprogress-0.3.4}/src/asyncprogress/_renderer.py

@@ -1,48 +1,47 @@
 """
-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
 
-ANSI_COLORS: dict[str, str] = {
-    "black": "\033[30m",
-    "red": "\033[31m",
-    "green": "\033[32m",
-    "yellow": "\033[33m",
-    "blue": "\033[34m",
-    "magenta": "\033[35m",
-    "cyan": "\033[36m",
-    "white": "\033[37m",
-    "bright_black": "\033[90m",
-    "bright_red": "\033[91m",
-    "bright_green": "\033[92m",
-    "bright_yellow": "\033[93m",
-    "bright_blue": "\033[94m",
-    "bright_magenta": "\033[95m",
-    "bright_cyan": "\033[96m",
-    "bright_white": "\033[97m",
-}
-
-ANSI_RESET = "\033[0m"
-
 SPINNER_FRAMES: list[str] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
 
+_ANSI_COLORS: dict[str, str] = {
+    "black": "\x1b[30m",
+    "red": "\x1b[31m",
+    "green": "\x1b[32m",
+    "yellow": "\x1b[33m",
+    "blue": "\x1b[34m",
+    "magenta": "\x1b[35m",
+    "cyan": "\x1b[36m",
+    "white": "\x1b[37m",
+    "bright_black": "\x1b[90m",
+    "bright_red": "\x1b[91m",
+    "bright_green": "\x1b[92m",
+    "bright_yellow": "\x1b[93m",
+    "bright_blue": "\x1b[94m",
+    "bright_magenta": "\x1b[95m",
+    "bright_cyan": "\x1b[96m",
+    "bright_white": "\x1b[97m",
+}
+_ANSI_RESET = "\x1b[0m"
+
 _SI_PREFIXES = ["", "K", "M", "G", "T", "P"]
 _BINARY_PREFIXES = ["", "Ki", "Mi", "Gi", "Ti", "Pi"]
 
 
 def _apply_color(text: str, color: str) -> str:
-    """Apply ANSI color to text."""
-    code = ANSI_COLORS.get(color.lower(), "")
+    """Apply ANSI color to text, returning the colored string."""
+    code = _ANSI_COLORS.get(color.lower(), "")
     if not code:
         return text
-    return f"{code}{text}{ANSI_RESET}"
+    return f"{code}{text}{_ANSI_RESET}"
 
 
 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:
@@ -64,22 +63,22 @@ class BarRenderer:
     """
     Renders progress bar strings for terminal output.
 
-    No I/O performed here — returns strings only.
+    String formatting only — no I/O side effects.
     """
 
     def _compute_percentage(self, completed: int, total: int) -> float:
-        """Compute percentage, handling zero total."""
+        """Compute percentage, handling zero total gracefully."""
         if total == 0:
-            return 100.0
+            return 100.0  # Empty collection is trivially complete
         return min(100.0, (completed / total) * 100.0)
 
     def _format_count(
         self,
         completed: int,
         total: int | None,
-        unit: str = "it",
-        unit_scale: bool = False,
-        unit_divisor: int = 1000,
+        unit: str,
+        unit_scale: bool,
+        unit_divisor: int,
     ) -> str:
         """Format the count display string."""
         if not unit_scale:
@@ -95,17 +94,17 @@ class BarRenderer:
     def _format_rate(
         self,
         rate: float | None,
-        unit: str = "it",
-        unit_scale: bool = False,
-        unit_divisor: int = 1000,
+        unit: str,
+        unit_scale: bool,
+        unit_divisor: int,
     ) -> str:
         """Format the rate display string."""
         if rate is None:
             return ""
         if not unit_scale:
             return f"{rate:.1f} {unit}/s"
-        val, prefix = _scale_value(rate, unit_divisor)
-        return f"{val:.1f} {prefix}{unit}/s"
+        r_val, r_prefix = _scale_value(rate, unit_divisor)
+        return f"{r_val:.1f} {r_prefix}{unit}/s"
 
     def render(
         self,
@@ -152,27 +151,30 @@ class BarRenderer:
 
             # Count
             if show_count:
-                parts.append(self._format_count(completed, total, unit, unit_scale, unit_divisor))
+                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))
+                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)}")
 
-        # Rate
-        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(parts)
+        line = "  ".join(parts)
         if color:
             line = _apply_color(line, color)
         return line

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

@@ -1,5 +1,5 @@
 """
-Terminal utilities: TTY detection, ANSI cursor control sequences.
+Terminal utilities: TTY detection, ANSI escape sequences, cursor control.
 """
 
 from __future__ import annotations
@@ -10,29 +10,24 @@ from typing import TextIO
 
 def is_tty(file: TextIO = sys.stderr) -> bool:
     """Return True if the given file is a TTY."""
-    try:
-        return file.isatty()
-    except AttributeError:
-        return False
+    return hasattr(file, "isatty") and file.isatty()
 
 
 def move_cursor_up(n: int = 1) -> str:
     """Return ANSI escape sequence to move cursor up n lines."""
-    if n <= 0:
-        return ""
-    return f"\033[{n}A"
+    return f"\x1b[{n}A"
 
 
 def erase_line() -> str:
     """Return ANSI escape sequence to erase the current line."""
-    return "\033[2K\r"
+    return "\x1b[2K\r"
 
 
 def hide_cursor() -> str:
     """Return ANSI escape sequence to hide the cursor."""
-    return "\033[?25l"
+    return "\x1b[?25l"
 
 
 def show_cursor() -> str:
     """Return ANSI escape sequence to show the cursor."""
-    return "\033[?25h"
+    return "\x1b[?25h"

asyncprogress-0.3.0/README.md

@@ -1,22 +0,0 @@
-# asyncprogress
-
-Async-aware progress bars for Python's asyncio ecosystem. Zero dependencies, native `async for` support, accurate ETA with EWMA, and concurrent task tracking.
-
-## Features
-
-- **Native `async for` support** — wrap any sync or async iterable
-- **`async with` context manager** — manual progress tracking
-- **`gather()` replacement** — drop-in for `asyncio.gather()` with progress
-- **`aprogress_as_completed()`** — progress-tracked `as_completed` wrapper
-- **Spinner mode** — automatic for indeterminate progress
-- **EWMA-based ETA** — accurate estimates for bursty async workloads
-- **Multiple concurrent bars** — `MultiProgressBar` for parallel streams
-- **Zero mandatory dependencies** — stdlib only
-
-## Installation
-
-
-
-```bash
-pip install asyncprogress
-```

asyncprogress-0.3.0/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