asyncprogress 0.3.1__tar.gz → 0.3.5__tar.gz

{asyncprogress-0.3.1 → asyncprogress-0.3.5}/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.5
+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
@@ -19,11 +19,11 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
 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
+Project-URL: Homepage, https://github.com/agentsoft/asyncprogress
+Project-URL: Repository, https://github.com/agentsoft/asyncprogress
 Description-Content-Type: text/markdown
 
 # asyncprogress
@@ -36,13 +36,15 @@ 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 designed for
+synchronous code. `asyncprogress` is built from the ground up for `asyncio`:
 
-- **Native `async for` support** — wrap any sync or async iterable
+- **Native `async for` support** — wrap any sync or async iterable with one line
 - **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`
+- **Multiple concurrent bars** — `MultiProgressBar` for parallel pipelines
+- **Zero mandatory dependencies** — pure Python stdlib (`asyncio`, `sys`, `time`)
 
 ## Installation
 

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

@@ -8,13 +8,15 @@ 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 designed for
+synchronous code. `asyncprogress` is built from the ground up for `asyncio`:
 
-- **Native `async for` support** — wrap any sync or async iterable
+- **Native `async for` support** — wrap any sync or async iterable with one line
 - **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`
+- **Multiple concurrent bars** — `MultiProgressBar` for parallel pipelines
+- **Zero mandatory dependencies** — pure Python stdlib (`asyncio`, `sys`, `time`)
 
 ## Installation
 

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

@@ -1,12 +1,12 @@
 [tool.poetry]
 name = "asyncprogress"
-version = "0.3.1"
-description = "Async-aware progress bars for Python's asyncio ecosystem"
+version = "0.3.5"
+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"
+homepage = "https://github.com/agentsoft/asyncprogress"
+repository = "https://github.com/agentsoft/asyncprogress"
 keywords = ["asyncio", "progress", "progress-bar", "async", "tqdm"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
     "Framework :: AsyncIO",
 ]
 packages = [{include = "asyncprogress", from = "src"}]
@@ -42,23 +42,19 @@ 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
 target-version = "py39"
 
 [tool.ruff.lint]
-select = ["E", "F", "W", "I", "UP"]
+select = ["E", "F", "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.5}/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.5"

{asyncprogress-0.3.1 → asyncprogress-0.3.5}/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
 
@@ -17,29 +19,35 @@ 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:
-                await process(item)
-                await bar.update()
+    Provides a progress bar with EWMA-based ETA estimation, configurable
+    appearance, and non-blocking terminal output.
 
     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.
-        ewma_alpha: EWMA smoothing factor (0 < alpha <= 1).
-        file: Output file (default: sys.stderr).
+        fill_char: Character for completed portion.
+        empty_char: Character for remaining portion.
+        color: ANSI color name (e.g., "green", "cyan", "red").
+        show_eta: Whether to show estimated time remaining.
+        show_elapsed: Whether to show elapsed time.
+        show_count: Whether to show [completed/total] count.
+        show_percentage: Whether to show percentage.
+        update_interval: Seconds between terminal redraws.
+        ewma_alpha: EWMA smoothing factor (0.1=smooth, 0.5=reactive).
+        file: Output stream (default: sys.stderr).
         disable: If True, suppress all output.
+        unit: Unit label ("it" for items, "B" for bytes, etc.).
+        unit_scale: If True, auto-apply SI prefix (K/M/G).
+        unit_divisor: 1000 for SI, 1024 for binary.
+
+    Example:
+        async with ProgressBar(total=100, description="Processing") as bar:
+            for item in items:
+                await process(item)
+                await bar.update()
     """
 
     def __init__(
@@ -58,6 +66,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 +83,48 @@ 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._running: bool = False
 
         self._eta_calc = EWMACalculator(alpha=ewma_alpha)
         self._renderer = BarRenderer()
-        self._render_task: asyncio.Task[None] | None = None
 
     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._spinner_frame = 0
-        self._eta_calc.reset()
-        await self._schedule_render()
+        self._last_render_time = self._start_time
+        self._running = True
+        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()
+        self._running = False
+        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 re-renders the bar."""
+        while self._running:
+            await asyncio.sleep(self._update_interval)
+            if self._running and not self._finished:
+                self._write_line(self._get_render_string())
 
     def _get_render_string(self) -> str:
         """Build the current render string (spinner or bar)."""
@@ -181,6 +139,9 @@ class ProgressBar:
                 color=self._color,
                 show_elapsed=self._show_elapsed,
                 show_count=self._show_count,
+                unit=self._unit,
+                unit_scale=self._unit_scale,
+                unit_divisor=self._unit_divisor,
             )
         return self._renderer.render(
             description=self._description,
@@ -197,38 +158,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."""
-        if self._disable:
-            return
-        now = time.monotonic()
-        if now - self._last_render_time >= self._update_interval:
-            self._last_render_time = now
-            self._write_line(self._get_render_string())
-
-    def _write_line(self, line: str) -> None:
-        """Write a single progress line to the output file."""
+    def _write_line(self, text: str) -> None:
+        """Write a progress line to the output file."""
         if self._disable:
             return
         if is_tty(self._file):
-            self._file.write(erase_line() + line + "\r")
+            self._file.write(erase_line() + text)
         else:
-            self._file.write(line + "\n")
+            self._file.write("\r" + text)
         self._file.flush()
 
     async def _render_final(self) -> None:
-        """Write the final completed state."""
+        """Render the final completed state."""
         if self._disable:
             return
         line = self._get_render_string()
         if is_tty(self._file):
             self._file.write(erase_line() + line + "\n")
         else:
-            self._file.write(line + "\n")
+            self._file.write("\r" + line + "\n")
         self._file.flush()
 
+    async def _schedule_render(self) -> None:
+        """Trigger an immediate 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())
+
+    async def update(self, n: int = 1) -> None:
+        """
+        Increment progress by n steps.
+
+        No-op if the bar has already been finished.
+        Clamps to total if total is set.
+        """
+        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].
+
+        No-op if the bar has already been finished.
+        """
+        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 — 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()
+
+    @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()
+
+    @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
+
     @classmethod
     def track(
         cls,
@@ -241,14 +286,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 constructor.
 
         Yields:
             Items from the iterable, in order.

{asyncprogress-0.3.1 → asyncprogress-0.3.5}/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 — no I/O, fully unit-testable.
 """
 
 from __future__ import annotations
@@ -11,16 +11,17 @@ 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.
+        alpha: Smoothing factor (0 < alpha <= 1).
+               Higher values give more weight to recent samples.
                Recommended range: 0.1 (smooth) to 0.5 (reactive).
     """
 
     def __init__(self, alpha: float = 0.3) -> None:
-        if not (0 < alpha <= 1.0):
+        if not (0 < alpha <= 1):
             raise ValueError(f"alpha must be in (0, 1], got {alpha}")
         self._alpha = alpha
         self._ewma_rate: float | None = None
@@ -40,16 +41,16 @@ class EWMACalculator:
                     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 dt == 0, we skip updating the rate (same timestamp)
         self._last_timestamp = timestamp
         self._last_completed = completed
 
     def rate(self) -> float | None:
-        """Returns smoothed items/second, or None if insufficient data."""
+        """Return smoothed items/second, or None if insufficient data."""
         return self._ewma_rate
 
     def eta(self, remaining: int) -> float | None:
-        """Returns estimated seconds to completion, or None if unknown."""
+        """Return estimated seconds to completion, or None if unknown."""
         if remaining == 0:
             return 0.0
         r = self.rate()

{asyncprogress-0.3.1 → asyncprogress-0.3.5}/src/asyncprogress/_gather.py

@@ -1,6 +1,4 @@
-"""
-gather() — Drop-in replacement for asyncio.gather() with progress tracking.
-"""
+"""gather() — drop-in replacement for asyncio.gather() with progress tracking."""
 
 from __future__ import annotations
 
@@ -20,22 +18,22 @@ async def gather(
     """
     Drop-in replacement for asyncio.gather() with progress tracking.
 
-    Returns results in the same order as inputs, matching asyncio.gather() semantics.
+    Returns results in the same order as inputs.
 
     Args:
         *coros_or_tasks: Coroutines or Tasks to run concurrently.
         description: Label shown on the progress bar.
-        return_exceptions: If True, exceptions are returned as results
-                           rather than raised (mirrors asyncio.gather behavior).
+        return_exceptions: If True, exceptions are returned as values.
         **progress_kwargs: Forwarded to ProgressBar (color, bar_width, etc.)
 
     Returns:
-        List of results in the same order as inputs.
+        List of results in submission order.
 
     Example:
         results = await gather(
             *[fetch(url) for url in urls],
-            description="Downloading",
+            description="Fetching",
+            color="cyan",
         )
     """
     if not coros_or_tasks:
@@ -48,26 +46,27 @@ async def gather(
     ) as bar:
         # Wrap each coroutine/task to update the bar on completion
         results: list[Any] = [None] * total
+        exceptions: list[BaseException | None] = [None] * total
 
-        async def _run_and_update(idx: int, coro: Any) -> None:
+        async def _run_one(idx: int, coro: Any) -> None:
             try:
                 results[idx] = await coro
-            except Exception as exc:
-                if return_exceptions:
-                    results[idx] = exc
-                else:
-                    raise
+            except Exception as exc:  # noqa: BLE001
+                exceptions[idx] = exc
             finally:
                 await bar.update()
 
-        wrapped = [
-            asyncio.create_task(_run_and_update(i, coro))
-            for i, coro in enumerate(coros_or_tasks)
-        ]
+        tasks = [asyncio.create_task(_run_one(i, c)) for i, c in enumerate(coros_or_tasks)]
+        await asyncio.gather(*tasks, return_exceptions=True)
 
-        if return_exceptions:
-            await asyncio.gather(*wrapped, return_exceptions=True)
+    # Re-raise or return exceptions based on return_exceptions flag
+    final: list[Any] = []
+    for i in range(total):
+        if exceptions[i] is not None:
+            if return_exceptions:
+                final.append(exceptions[i])
+            else:
+                raise exceptions[i]  # type: ignore[misc]
         else:
-            await asyncio.gather(*wrapped)
-
-    return results
+            final.append(results[i])
+    return final

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

@@ -1,5 +1,5 @@
 """
-aprogress() — Async generator wrapper for iterables with progress tracking.
+aprogress() — async generator wrapper for iterables.
 """
 
 from __future__ import annotations
@@ -32,50 +32,49 @@ async def aprogress(
     unit: str = "it",
     unit_scale: bool = False,
     unit_divisor: int = 1000,
-    **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.
+    Automatically infers total from __len__ if 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: Whether to show estimated time remaining.
+        show_elapsed: Whether to show elapsed time.
+        show_count: Whether to show [completed/total] count.
+        show_percentage: Whether to show percentage.
         update_interval: Seconds between terminal redraws.
         ewma_alpha: EWMA smoothing factor.
-        file: Output file (default: sys.stderr).
+        file: Output stream (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.
+        unit: Unit label ("it" for items, "B" for bytes, etc.).
+        unit_scale: If True, auto-apply SI prefix (K/M/G).
+        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(range(100), description="Processing"):
             await process(item)
     """
     import sys as _sys
 
+    # Infer total from __len__ if available
     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
 
-    bar_kwargs: dict[str, Any] = {
+    kwargs: dict[str, Any] = {
         "total": effective_total,
         "description": description,
         "bar_width": bar_width,
@@ -88,15 +87,17 @@ async def aprogress(
         "show_percentage": show_percentage,
         "update_interval": update_interval,
         "ewma_alpha": ewma_alpha,
-        "file": file if file is not None else _sys.stderr,
         "disable": disable,
         "unit": unit,
         "unit_scale": unit_scale,
         "unit_divisor": unit_divisor,
     }
-    bar_kwargs.update(kwargs)
+    if file is not None:
+        kwargs["file"] = file
+    else:
+        kwargs["file"] = _sys.stderr
 
-    async with ProgressBar(**bar_kwargs) as bar:
+    async with ProgressBar(**kwargs) as bar:
         count = 0
         if hasattr(iterable, "__aiter__"):
             async for item in iterable:  # type: ignore[union-attr]
@@ -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.5}/src/asyncprogress/_renderer.py

@@ -1,45 +1,37 @@
 """
-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
 
 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_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 = "\x1b[0m"
+ANSI_RESET = "\033[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, returning reset at end."""
-    code = _ANSI_COLORS.get(color.lower(), "")
-    if not code:
-        return text
-    return f"{code}{text}{_ANSI_RESET}"
-
-
 def _format_duration(seconds: float) -> str:
     """Format seconds as H:MM:SS or M:SS."""
     m, s = divmod(int(seconds), 60)
@@ -49,6 +41,14 @@ def _format_duration(seconds: float) -> str:
     return f"{m}:{s:02d}"
 
 
+def _apply_color(text: str, color: str) -> str:
+    """Apply ANSI color to text."""
+    code = ANSI_COLORS.get(color.lower(), "")
+    if not code:
+        return text
+    return f"{code}{text}{ANSI_RESET}"
+
+
 def _scale_value(value: float, divisor: int) -> tuple[float, str]:
     """Return (scaled_value, prefix_string) for display."""
     prefixes = _BINARY_PREFIXES if divisor == 1024 else _SI_PREFIXES
@@ -61,9 +61,9 @@ def _scale_value(value: float, divisor: int) -> tuple[float, str]:
 
 class BarRenderer:
     """
-    Renders progress bar strings for terminal output.
+    Renders a single-line progress bar string.
 
-    String formatting only — no I/O performed here.
+    No I/O — returns strings only. Fully unit-testable.
     """
 
     def _compute_percentage(self, completed: int, total: int) -> float:
@@ -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:
@@ -128,7 +128,7 @@ class BarRenderer:
         unit_divisor: int = 1000,
     ) -> str:
         """
-        Render a single-line progress bar string.
+        Render a single-line deterministic progress bar string.
 
         Returns a string ready for terminal output (no newline).
         """
@@ -139,9 +139,9 @@ class BarRenderer:
 
         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} ")
 
             if show_percentage:
                 parts.append(f"{pct:.0f}%")
@@ -151,7 +151,6 @@ class BarRenderer:
                     self._format_count(completed, total, unit, unit_scale, unit_divisor)
                 )
         else:
-            # Indeterminate — no bar graphic
             if show_count:
                 parts.append(
                     self._format_count(completed, None, unit, unit_scale, unit_divisor)
@@ -163,12 +162,11 @@ class BarRenderer:
         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)
+        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
@@ -184,19 +182,34 @@ class BarRenderer:
         color: str | None,
         show_elapsed: bool = True,
         show_count: bool = True,
+        unit: str = "it",
+        unit_scale: bool = False,
+        unit_divisor: int = 1000,
     ) -> str:
-        """Render a single-line spinner for indeterminate progress."""
+        """
+        Render a single-line spinner for indeterminate progress.
+
+        Activates automatically when total is None.
+        """
         spinner = SPINNER_FRAMES[frame_index % len(SPINNER_FRAMES)]
         parts: list[str] = []
         if description:
             parts.append(description)
         parts.append(spinner)
         if show_count:
-            parts.append(f"{completed} items")
+            if unit == "it":
+                parts.append(f"{completed} items")
+            else:
+                count_str = self._format_count(
+                    completed, None, unit, unit_scale, unit_divisor
+                )
+                parts.append(count_str)
         if show_elapsed:
             parts.append(f"⏱ {_format_duration(elapsed)}")
         if rate is not None:
-            parts.append(f"{rate:.1f} items/s")
+            rate_str = self._format_rate(rate, unit, unit_scale, unit_divisor)
+            if rate_str:
+                parts.append(rate_str)
         line = "  ".join(parts)
         if color:
             line = _apply_color(line, color)

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

@@ -1,5 +1,5 @@
 """
-Terminal utilities — TTY detection and ANSI escape sequences.
+Terminal utilities: TTY detection, ANSI cursor control.
 """
 
 from __future__ import annotations
@@ -15,19 +15,19 @@ def is_tty(file: TextIO = sys.stderr) -> bool:
 
 def move_cursor_up(n: int = 1) -> str:
     """Return ANSI escape sequence to move cursor up n lines."""
-    return f"\x1b[{n}A"
+    return f"\033[{n}A"
 
 
 def erase_line() -> str:
     """Return ANSI escape sequence to erase the current line."""
-    return "\x1b[2K\r"
+    return "\033[2K\r"
 
 
 def hide_cursor() -> str:
     """Return ANSI escape sequence to hide the cursor."""
-    return "\x1b[?25l"
+    return "\033[?25l"
 
 
 def show_cursor() -> str:
     """Return ANSI escape sequence to show the cursor."""
-    return "\x1b[?25h"
+    return "\033[?25h"