asyncprogress 0.2.1__tar.gz

asyncprogress-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asyncprogress-0.2.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: asyncprogress
+Version: 0.2.1
+Summary: Async-aware progress bars for Python's asyncio ecosystem. Zero mandatory dependencies.
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,progress,progress-bar,async,cli
+Author: AgentSoft
+Author-email: agentsoft@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Provides-Extra: color
+Requires-Dist: colorama (>=0.4.4) ; extra == "color"
+Project-URL: Homepage, https://github.com/agentsoft/asyncprogress
+Project-URL: Repository, https://github.com/agentsoft/asyncprogress
+Description-Content-Type: text/markdown
+
+# 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
+
+## Installation
+
+
+
+```bash
+pip install asyncprogress
+```

asyncprogress-0.2.1/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
+
+## Installation
+
+
+
+```bash
+pip install asyncprogress
+```

asyncprogress-0.2.1/pyproject.toml

@@ -0,0 +1,59 @@
+[tool.poetry]
+name = "asyncprogress"
+version = "0.2.1"
+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/agentsoft/asyncprogress"
+repository = "https://github.com/agentsoft/asyncprogress"
+keywords = ["asyncio", "progress", "progress-bar", "async", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Terminals",
+    "Framework :: AsyncIO",
+]
+packages = [{include = "asyncprogress", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+colorama = {version = ">=0.4.4", optional = true}
+
+[tool.poetry.extras]
+color = ["colorama"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-asyncio = "^0.23.0"
+pytest-cov = "^4.1.0"
+ruff = "^0.1.0"
+
+[build-system]
+requires = ["poetry-core"]
+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"
+
+[tool.ruff]
+src = ["src"]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "I", "W"]
+ignore = ["E501"]
+
+[tool.coverage.run]
+source = ["src/asyncprogress"]
+omit = ["*/tests/*"]

asyncprogress-0.2.1/src/asyncprogress/__init__.py

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

asyncprogress-0.2.1/src/asyncprogress/_as_completed.py

@@ -0,0 +1,59 @@
+"""
+aprogress_as_completed() — Progress-tracked asyncio.as_completed() wrapper.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Coroutine
+from typing import Any, TypeVar
+
+from asyncprogress._bar import ProgressBar
+
+T = TypeVar("T")
+
+
+async def aprogress_as_completed(
+    coros: list[Coroutine[Any, Any, T]],
+    *,
+    description: str = "",
+    return_exceptions: bool = False,
+    **progress_kwargs: Any,
+) -> AsyncIterator[T]:
+    """
+    Async generator that yields results as coroutines complete,
+    with a progress bar tracking completion.
+
+    Drop-in replacement for asyncio.as_completed() iteration patterns.
+    Results are yielded in completion order (not submission order).
+
+    Args:
+        coros: List of coroutines to run concurrently.
+        description: Label shown on the progress bar.
+        return_exceptions: If True, exceptions are yielded as values
+                           rather than raised (mirrors asyncio.gather behavior).
+        **progress_kwargs: Forwarded to ProgressBar (color, bar_width, etc.)
+
+    Yields:
+        Results in completion order.
+
+    Example:
+        async for result in aprogress_as_completed(coros, description="Fetching"):
+            process(result)
+    """
+    if not coros:
+        return
+
+    total = len(coros)
+    async with ProgressBar(total=total, description=description, **progress_kwargs) as bar:
+        for future in asyncio.as_completed(coros):
+            try:
+                result = await future
+                await bar.update()
+                yield result
+            except Exception as exc:
+                await bar.update()  # Always advance — task completed (with error)
+                if return_exceptions:
+                    yield exc  # type: ignore[misc]
+                else:
+                    raise

asyncprogress-0.2.1/src/asyncprogress/_bar.py

@@ -0,0 +1,262 @@
+"""Core ProgressBar class — async context manager with EWMA-based ETA."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+from collections.abc import AsyncGenerator, AsyncIterable, Iterable
+from typing import Any, TextIO, TypeVar
+
+from asyncprogress._eta import EWMACalculator
+from asyncprogress._renderer import BarRenderer
+from asyncprogress._terminal import erase_line, is_tty
+
+T = TypeVar("T")
+
+
+class ProgressBar:
+    """
+    Async context manager progress bar with EWMA-based ETA estimation.
+
+    Usage:
+        async with ProgressBar(total=100, description="Processing") as bar:
+            for item in data:
+                await process(item)
+                await bar.update()
+
+    Args:
+        total: Total number of steps. None for indeterminate (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).
+        disable: If True, suppress all output.
+    """
+
+    def __init__(
+        self,
+        total: int | None = None,
+        description: str = "",
+        bar_width: int = 40,
+        fill_char: str = "█",
+        empty_char: str = "░",
+        color: str | None = None,
+        show_eta: bool = True,
+        show_elapsed: bool = True,
+        show_count: bool = True,
+        show_percentage: bool = True,
+        update_interval: float = 0.1,
+        ewma_alpha: float = 0.3,
+        file: TextIO = sys.stderr,
+        disable: bool = False,
+    ) -> None:
+        self._total = total
+        self._description = description
+        self._bar_width = bar_width
+        self._fill_char = fill_char
+        self._empty_char = empty_char
+        self._color = color
+        self._show_eta = show_eta
+        self._show_elapsed = show_elapsed
+        self._show_count = show_count
+        self._show_percentage = show_percentage
+        self._update_interval = update_interval
+        self._file = file
+        self._disable = disable
+
+        self._completed: int = 0
+        self._finished: bool = False
+        self._start_time: float = 0.0
+        self._last_render_time: float = 0.0
+        self._spinner_frame: int = 0
+
+        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()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Finish the progress bar on context exit."""
+        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()
+
+    def _get_render_string(self) -> str:
+        """Build the current render string (spinner or bar)."""
+        if self._total is None:
+            self._spinner_frame += 1
+            return self._renderer.render_spinner(
+                description=self._description,
+                elapsed=self.elapsed,
+                completed=self._completed,
+                frame_index=self._spinner_frame,
+                rate=self.rate,
+                color=self._color,
+                show_elapsed=self._show_elapsed,
+                show_count=self._show_count,
+            )
+        return self._renderer.render(
+            description=self._description,
+            completed=self._completed,
+            total=self._total,
+            elapsed=self.elapsed,
+            eta=self.eta,
+            rate=self.rate,
+            bar_width=self._bar_width,
+            fill_char=self._fill_char,
+            empty_char=self._empty_char,
+            color=self._color,
+            show_eta=self._show_eta,
+            show_elapsed=self._show_elapsed,
+            show_count=self._show_count,
+            show_percentage=self._show_percentage,
+        )
+
+    async def _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."""
+        if self._disable:
+            return
+        if is_tty(self._file):
+            self._file.write(erase_line() + line + "\r")
+        else:
+            self._file.write(line + "\n")
+        self._file.flush()
+
+    async def _render_final(self) -> None:
+        """Write 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.flush()
+
+    @classmethod
+    def track(
+        cls,
+        iterable: AsyncIterable[T] | Iterable[T],
+        *,
+        total: int | None = None,
+        description: str = "",
+        **kwargs: Any,
+    ) -> AsyncGenerator[T, None]:
+        """
+        Convenience wrapper: iterate over iterable with a progress bar.
+
+        Equivalent to aprogress(iterable, total=total, description=description).
+        Provided as a classmethod for discoverability.
+
+        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.
+
+        Yields:
+            Items from the iterable, in order.
+
+        Example:
+            async for item in ProgressBar.track(my_list, description="Processing"):
+                await process(item)
+        """
+        from asyncprogress._iterator import aprogress
+
+        return aprogress(iterable, total=total, description=description, **kwargs)

asyncprogress-0.2.1/src/asyncprogress/_eta.py

@@ -0,0 +1,92 @@
+"""
+EWMACalculator — Exponential Weighted Moving Average for ETA estimation.
+
+Pure math; no I/O. Fully unit-testable.
+"""
+
+from __future__ import annotations
+
+
+class EWMACalculator:
+    """
+    Exponential Weighted Moving Average calculator for ETA estimation.
+
+    Uses EWMA over inter-completion intervals to smooth out bursty async
+    I/O patterns that would make simple linear regression inaccurate.
+
+    Args:
+        alpha: Smoothing factor in (0, 1]. Higher = more weight on 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):
+            raise ValueError(f"alpha must be in (0, 1], got {alpha}")
+        self._alpha = alpha
+        self._ewma_rate: float | None = None
+        self._last_timestamp: float | None = None
+        self._last_completed: int | None = None
+
+    def record(self, timestamp: float, completed: int) -> None:
+        """
+        Record a completion event.
+
+        Args:
+            timestamp: Monotonic timestamp (e.g., from time.monotonic()).
+            completed: Total number of items completed so far.
+        """
+        if self._last_timestamp is not None and self._last_completed is not None:
+            dt = timestamp - self._last_timestamp
+            dc = completed - self._last_completed
+            if dt > 0 and dc >= 0:
+                # Instantaneous rate for this interval
+                instant_rate = dc / dt
+                if self._ewma_rate is None:
+                    self._ewma_rate = instant_rate
+                else:
+                    # EWMA update
+                    self._ewma_rate = (
+                        self._alpha * instant_rate + (1 - self._alpha) * self._ewma_rate
+                    )
+            elif dt == 0 and dc == 0:
+                # Same timestamp, same count — no new information
+                pass
+            elif dt == 0 and dc > 0:
+                # Instantaneous completion — rate is effectively infinite
+                # Don't update EWMA to avoid division by zero artifacts
+                pass
+
+        self._last_timestamp = timestamp
+        self._last_completed = completed
+
+    def rate(self) -> float | None:
+        """
+        Return smoothed items/second rate, or None if insufficient data.
+
+        Returns:
+            EWMA-smoothed rate in items/second, or None if not enough data.
+        """
+        return self._ewma_rate
+
+    def eta(self, remaining: int) -> float | None:
+        """
+        Return estimated seconds to completion, or None if unknown.
+
+        Args:
+            remaining: Number of items still to be completed.
+
+        Returns:
+            Estimated seconds remaining, or None if rate is unknown/zero.
+        """
+        if remaining == 0:
+            return 0.0
+        r = self.rate()
+        if r is None or r <= 0.0:
+            return None
+        return remaining / r
+
+    def reset(self) -> None:
+        """Clear all recorded data and reset the calculator."""
+        self._ewma_rate = None
+        self._last_timestamp = None
+        self._last_completed = None

asyncprogress-0.2.1/src/asyncprogress/_gather.py

@@ -0,0 +1,73 @@
+"""
+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

asyncprogress-0.2.1/src/asyncprogress/_iterator.py

@@ -0,0 +1,113 @@
+"""
+aprogress() — Async generator wrapper for iterables with progress tracking.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterable, Iterable
+from typing import Any, TypeVar
+
+from asyncprogress._bar import ProgressBar
+
+T = TypeVar("T")
+
+
+async def aprogress(
+    iterable: AsyncIterable[T] | Iterable[T],
+    *,
+    total: int | None = None,
+    description: str = "",
+    bar_width: int = 40,
+    fill_char: str = "█",
+    empty_char: str = "░",
+    color: str | None = None,
+    show_eta: bool = True,
+    show_elapsed: bool = True,
+    show_count: bool = True,
+    show_percentage: bool = True,
+    update_interval: float = 0.1,
+    ewma_alpha: float = 0.3,
+    file: Any = None,
+    disable: bool = False,
+    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.
+
+    Supports both sync and async iterables. Automatically infers `total`
+    from `__len__` if available. Activates spinner mode when `total=None`
+    and no `__len__` is present.
+
+    Args:
+        iterable: Any sync or async iterable.
+        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.
+        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.
+        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.
+
+    Yields:
+        Items from the iterable, in order.
+
+    Example:
+        async for item in aprogress(items, description="Processing"):
+            await process(item)
+    """
+    import sys as _sys
+
+    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] = {
+        "total": effective_total,
+        "description": description,
+        "bar_width": bar_width,
+        "fill_char": fill_char,
+        "empty_char": empty_char,
+        "color": color,
+        "show_eta": show_eta,
+        "show_elapsed": show_elapsed,
+        "show_count": show_count,
+        "show_percentage": show_percentage,
+        "update_interval": update_interval,
+        "ewma_alpha": ewma_alpha,
+        "file": file if file is not None else _sys.stderr,
+        "disable": disable,
+        "unit": unit,
+        "unit_scale": unit_scale,
+        "unit_divisor": unit_divisor,
+    }
+    bar_kwargs.update(kwargs)
+
+    async with ProgressBar(**bar_kwargs) as bar:
+        count = 0
+        if hasattr(iterable, "__aiter__"):
+            async for item in iterable:  # type: ignore[union-attr]
+                count += 1
+                yield item
+                await bar.update()
+        else:
+            for item in iterable:  # type: ignore[union-attr]
+                count += 1
+                yield item
+                await bar.update()
+
+        if count == 0:
+            await bar.finish()

asyncprogress-0.2.1/src/asyncprogress/_multi.py

@@ -0,0 +1,163 @@
+"""
+MultiProgressBar — Concurrent multi-bar manager.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any, TextIO
+
+from asyncprogress._bar import ProgressBar
+from asyncprogress._terminal import erase_line, is_tty, move_cursor_up
+
+
+class MultiProgressBar:
+    """
+    Async context manager for displaying multiple concurrent progress bars.
+
+    Manages a shared render loop that redraws all registered bars together.
+
+    Args:
+        file: Output file (default: sys.stderr).
+        update_interval: Seconds between terminal redraws.
+        disable: If True, suppress all output.
+
+    Usage:
+        async with MultiProgressBar() as multi:
+            bar1 = multi.add("Downloads", total=50)
+            bar2 = multi.add("Processing", total=200)
+            # ... use bar1.update() and bar2.update() concurrently
+    """
+
+    def __init__(
+        self,
+        file: TextIO = sys.stderr,
+        update_interval: float = 0.1,
+        disable: bool = False,
+    ) -> None:
+        self._file = file
+        self._update_interval = update_interval
+        self._disable = disable
+        self._bars: list[ProgressBar] = []
+        self._running: bool = False
+        self._render_task: asyncio.Task[None] | None = None
+        self._lines_rendered: int = 0
+
+    async def __aenter__(self) -> MultiProgressBar:
+        self._running = True
+        self._lines_rendered = 0
+        self._render_task = asyncio.create_task(self._render_loop())
+        await asyncio.sleep(0)  # Yield once so task initializes before caller proceeds
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        self._running = False
+        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._write_final_frame()
+
+    async def _render_loop(self) -> None:
+        """Background task that periodically redraws all bars."""
+        while self._running:
+            self._write_frame()
+            await asyncio.sleep(self._update_interval)
+
+    def _render_all_bars(self) -> str:
+        """Render all bars to a single string."""
+        lines = []
+        for bar in self._bars:
+            lines.append(bar._get_render_string())  # noqa: SLF001
+        return "\n".join(lines)
+
+    def _write_frame(self) -> None:
+        """Write the current frame to the output file."""
+        if self._disable or not self._bars:
+            return
+        output = self._render_all_bars()
+        if not output:
+            return
+
+        tty = is_tty(self._file)
+        if tty and self._lines_rendered > 0:
+            # Move cursor up to overwrite previous frame
+            self._file.write(move_cursor_up(self._lines_rendered))
+            for _ in range(self._lines_rendered):
+                self._file.write(erase_line())
+                self._file.write("\n")
+            self._file.write(move_cursor_up(self._lines_rendered))
+
+        self._file.write(output)
+        self._file.flush()
+        self._lines_rendered = len(self._bars)
+
+    def _write_final_frame(self) -> None:
+        """Write the final state of all bars."""
+        if self._disable or not self._bars:
+            return
+        output = self._render_all_bars()
+        if not output:
+            return
+
+        tty = is_tty(self._file)
+        if tty and self._lines_rendered > 0:
+            self._file.write(move_cursor_up(self._lines_rendered))
+            for _ in range(self._lines_rendered):
+                self._file.write(erase_line())
+                self._file.write("\n")
+            self._file.write(move_cursor_up(self._lines_rendered))
+
+        self._file.write(output)
+        self._file.write("\n")
+        self._file.flush()
+
+    def add(
+        self,
+        description: str = "",
+        total: int | None = None,
+        **bar_kwargs: Any,
+    ) -> ProgressBar:
+        """
+        Register a new progress bar.
+
+        Returns a ProgressBar instance that shares this manager's rendering loop.
+
+        Args:
+            description: Label for this bar.
+            total: Total steps for this bar.
+            **bar_kwargs: Additional ProgressBar parameters.
+
+        Returns:
+            A ProgressBar instance (not yet started as context manager).
+        """
+        bar = ProgressBar(
+            total=total,
+            description=description,
+            file=self._file,
+            disable=True,  # Disable individual rendering; multi handles it
+            **bar_kwargs,
+        )
+        # Manually set start time since we're not using __aenter__
+        import time
+
+        bar._start_time = time.monotonic()  # noqa: SLF001
+        self._bars.append(bar)
+        return bar
+
+    def remove(self, bar: ProgressBar) -> None:
+        """
+        Remove a bar from the display.
+
+        No-op if bar is not registered.
+
+        Args:
+            bar: The ProgressBar to remove.
+        """
+        try:
+            self._bars.remove(bar)
+        except ValueError:
+            pass  # Already removed or never added — safe to ignore

asyncprogress-0.2.1/src/asyncprogress/_renderer.py

@@ -0,0 +1,240 @@
+"""
+Terminal bar renderer: string formatting only, no I/O.
+
+Produces single-line progress bar strings and spinner strings
+ready for terminal output.
+"""
+
+from __future__ import annotations
+
+# ANSI color codes
+_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] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+_SI_PREFIXES = ["", "K", "M", "G", "T", "P"]
+_BINARY_PREFIXES = ["", "Ki", "Mi", "Gi", "Ti", "Pi"]
+
+
+def _apply_color(text: str, color: str) -> str:
+    """Wrap text in ANSI color codes."""
+    code = _ANSI_COLORS.get(color.lower(), "")
+    if not code:
+        return text
+    return f"{code}{text}{_ANSI_RESET}"
+
+
+def _format_duration(seconds: float) -> str:
+    """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:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"
+
+
+def _scale_value(value: float, divisor: int) -> tuple[float, str]:
+    """Return (scaled_value, prefix_string) for SI or binary display."""
+    prefixes = _BINARY_PREFIXES if divisor == 1024 else _SI_PREFIXES
+    for prefix in prefixes[:-1]:
+        if abs(value) < divisor:
+            return value, prefix
+        value /= divisor
+    return value, prefixes[-1]
+
+
+class BarRenderer:
+    """
+    Renders progress bar strings for terminal output.
+
+    This class is pure string formatting — no I/O is performed here.
+    All rendering logic is centralized here for testability.
+    """
+
+    def _compute_percentage(self, completed: int, total: int) -> float:
+        """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)
+
+    def _format_count(
+        self,
+        completed: int,
+        total: int | None,
+        unit: str,
+        unit_scale: bool,
+        unit_divisor: int,
+    ) -> str:
+        """Format the count portion of the progress bar."""
+        if not unit_scale:
+            if total is not None:
+                return f"[{completed}/{total} {unit}]"
+            return f"[{completed} {unit}]"
+        c_val, c_prefix = _scale_value(float(completed), unit_divisor)
+        if total is not None:
+            t_val, t_prefix = _scale_value(float(total), unit_divisor)
+            return f"[{c_val:.1f}{c_prefix}{unit}/{t_val:.1f}{t_prefix}{unit}]"
+        return f"[{c_val:.1f}{c_prefix}{unit}]"
+
+    def _format_rate(
+        self,
+        rate: float | None,
+        unit: str,
+        unit_scale: bool,
+        unit_divisor: int,
+    ) -> str:
+        """Format the rate/throughput portion."""
+        if rate is None:
+            return ""
+        if not unit_scale:
+            return f"{rate:.1f} {unit}/s"
+        r_val, r_prefix = _scale_value(rate, unit_divisor)
+        return f"{r_val:.1f} {r_prefix}{unit}/s"
+
+    def render(
+        self,
+        *,
+        description: str,
+        completed: int,
+        total: int | None,
+        elapsed: float,
+        eta: float | None,
+        rate: float | None,
+        bar_width: int,
+        fill_char: str,
+        empty_char: str,
+        color: str | None,
+        show_eta: bool,
+        show_elapsed: bool,
+        show_count: bool,
+        show_percentage: bool,
+        unit: str = "it",
+        unit_scale: bool = False,
+        unit_divisor: int = 1000,
+    ) -> str:
+        """
+        Render a single-line deterministic progress bar string.
+
+        Args:
+            description: Label text shown before the bar.
+            completed: Number of items completed.
+            total: Total items (must not be None for deterministic bar).
+            elapsed: Seconds elapsed since start.
+            eta: Estimated seconds remaining, or None.
+            rate: EWMA-smoothed items/second, or None.
+            bar_width: Width of the bar graphic in characters.
+            fill_char: Character for completed portion.
+            empty_char: Character for remaining portion.
+            color: ANSI color name, or None for no color.
+            show_eta: Whether to show ETA.
+            show_elapsed: Whether to show elapsed time.
+            show_count: Whether to show count.
+            show_percentage: Whether to show percentage.
+            unit: Unit label.
+            unit_scale: Whether to auto-scale units.
+            unit_divisor: Divisor for unit scaling.
+
+        Returns:
+            A single-line string ready for terminal output.
+        """
+        parts: list[str] = []
+
+        if description:
+            parts.append(description)
+
+        if total is not None:
+            pct = self._compute_percentage(completed, total)
+            filled = int(bar_width * pct / 100)
+            bar = fill_char * filled + empty_char * (bar_width - filled)
+            bar_str = f"|{bar}|"
+            if color:
+                bar_str = _apply_color(bar_str, color)
+            parts.append(bar_str)
+
+            if show_percentage:
+                parts.append(f"{pct:.0f}%")
+
+            if show_count:
+                parts.append(self._format_count(completed, total, unit, unit_scale, unit_divisor))
+        else:
+            if show_count:
+                parts.append(self._format_count(completed, None, unit, unit_scale, unit_divisor))
+
+        if show_elapsed:
+            parts.append(f"⏱ {_format_duration(elapsed)}")
+
+        if show_eta and eta is not None:
+            parts.append(f"ETA: {_format_duration(eta)}")
+
+        rate_str = self._format_rate(rate, unit, unit_scale, unit_divisor)
+        if rate_str:
+            parts.append(rate_str)
+
+        return "  ".join(parts)
+
+    def render_spinner(
+        self,
+        *,
+        description: str,
+        elapsed: float,
+        completed: int,
+        frame_index: int,
+        rate: float | None,
+        color: str | None,
+        show_elapsed: bool = True,
+        show_count: bool = True,
+    ) -> str:
+        """
+        Render a single-line spinner for indeterminate progress.
+
+        Args:
+            description: Label text.
+            elapsed: Seconds elapsed since start.
+            completed: Number of items completed so far.
+            frame_index: Current spinner frame index (cycles through SPINNER_FRAMES).
+            rate: EWMA-smoothed items/second, or None.
+            color: ANSI color name, or None.
+            show_elapsed: Whether to show elapsed time.
+            show_count: Whether to show item count.
+
+        Returns:
+            A single-line spinner string.
+        """
+        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 show_elapsed:
+            parts.append(f"⏱ {_format_duration(elapsed)}")
+
+        if rate is not None:
+            parts.append(f"{rate:.1f} items/s")
+
+        line = "  ".join(parts)
+        if color:
+            line = _apply_color(line, color)
+        return line

asyncprogress-0.2.1/src/asyncprogress/_terminal.py

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