batchly 0.1.0__py3-none-any.whl

batchly/__init__.py

@@ -0,0 +1,28 @@
+"""batchly — Batch processing made simple."""
+
+from .batch import Batch, batch
+from .errors import BatchError, TimeoutError
+from .filter_ import async_batch_filter, batch_filter
+from .foreach import async_batch_for_each, batch_for_each
+from .map_ import async_batch_map, batch_map
+from .progress import ProgressBar, ProgressInfo
+from .rate_limit import RateLimiter
+from .result import BatchResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "batch",
+    "Batch",
+    "batch_map",
+    "async_batch_map",
+    "batch_filter",
+    "async_batch_filter",
+    "batch_for_each",
+    "async_batch_for_each",
+    "BatchResult",
+    "BatchError",
+    "TimeoutError",
+    "ProgressBar",
+    "ProgressInfo",
+    "RateLimiter",
+]

batchly/batch.py

@@ -0,0 +1,136 @@
+"""@batch decorator and Batch context class."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable
+
+from .filter_ import async_batch_filter, batch_filter
+from .foreach import async_batch_for_each, batch_for_each
+from .map_ import async_batch_map, batch_map
+
+
+class Batch:
+    """Reusable batch processing context.
+
+    Usage:
+        b = Batch(max_workers=10, retries=3)
+        results = b.map(fn, items)
+        filtered = b.filter(pred, items)
+        b.foreach(fn, items)
+    """
+
+    def __init__(
+        self,
+        *,
+        max_workers: int = 4,
+        retries: int = 0,
+        backoff: str = "exponential",
+        retry_on: tuple[type[Exception], ...] = (Exception,),
+        on_error: str = "skip",
+        chunk_size: int | None = None,
+        rate_limit: int | None = None,
+        ordered: bool = True,
+        timeout: float | None = None,
+        progress: Callable | None = None,
+    ):
+        self.max_workers = max_workers
+        self.retries = retries
+        self.backoff = backoff
+        self.retry_on = retry_on
+        self.on_error = on_error
+        self.chunk_size = chunk_size
+        self.rate_limit = rate_limit
+        self.ordered = ordered
+        self.timeout = timeout
+        self.progress = progress
+
+    def _common_kwargs(self) -> dict:
+        return dict(
+            max_workers=self.max_workers,
+            retries=self.retries,
+            backoff=self.backoff,
+            retry_on=self.retry_on,
+            on_error=self.on_error,
+            chunk_size=self.chunk_size,
+            rate_limit=self.rate_limit,
+            ordered=self.ordered,
+            timeout=self.timeout,
+            progress=self.progress,
+        )
+
+    def map(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return batch_map(fn, items, **kw)
+
+    async def amap(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return await async_batch_map(fn, items, **kw)
+
+    def filter(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return batch_filter(fn, items, **kw)
+
+    async def afilter(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return await async_batch_filter(fn, items, **kw)
+
+    def foreach(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return batch_for_each(fn, items, **kw)
+
+    async def aforeach(self, fn: Callable, items, **overrides):
+        kw = {**self._common_kwargs(), **overrides}
+        return await async_batch_for_each(fn, items, **kw)
+
+
+def batch(*, max_workers: int = 4, retries: int = 0, **kwargs) -> Callable:
+    """Decorator to turn a single-item function into a batch processor.
+
+    Usage:
+        @batch(max_workers=10, retries=3)
+        def process(item):
+            ...
+
+        results = process([1, 2, 3])  # processes all in parallel
+        single = process(42)          # calls directly for single item
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        _ctx = Batch(max_workers=max_workers, retries=retries, **kwargs)
+
+        @functools.wraps(fn)
+        def wrapper(items_or_single):
+            # If it's a single item (not iterable of items), call directly
+            if isinstance(items_or_single, (str, bytes, bytearray)):
+                # Strings are iterable but usually single items
+                if len(items_or_single) <= 1:
+                    return fn(items_or_single)
+                # Multi-char string: treat as single item
+                return fn(items_or_single)
+
+            try:
+                iter(items_or_single)
+            except TypeError:
+                # Not iterable — single item
+                return fn(items_or_single)
+
+            # It's iterable — batch process
+            return _ctx.map(fn, list(items_or_single))
+
+        @functools.wraps(fn)
+        async def async_wrapper(items_or_single):
+            if isinstance(items_or_single, (str, bytes, bytearray)):
+                return await fn(items_or_single)
+            try:
+                iter(items_or_single)
+            except TypeError:
+                return await fn(items_or_single)
+            return await _ctx.amap(fn, list(items_or_single))
+
+        if inspect.iscoroutinefunction(fn):
+            return async_wrapper
+        return wrapper
+
+    return decorator

batchly/errors.py

@@ -0,0 +1,14 @@
+"""Custom errors for batchly."""
+
+
+class BatchError(Exception):
+    """Raised when a batch operation fails (on_error='raise')."""
+
+    def __init__(self, message: str, item=None, original_error: Exception | None = None):
+        super().__init__(message)
+        self.item = item
+        self.original_error = original_error
+
+
+class TimeoutError(BatchError):
+    """Raised when an item exceeds its timeout."""

batchly/filter_.py

@@ -0,0 +1,36 @@
+"""batch_filter implementation."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Iterable
+
+from .map_ import batch_map, async_batch_map
+
+
+def batch_filter(
+    fn: Callable[..., bool],
+    items: Iterable[Any],
+    **kwargs,
+) -> list:
+    """Filter items where fn(item) is truthy, processing in parallel.
+
+    Returns list of items (not BatchResult) that pass the filter.
+    """
+    if inspect.iscoroutinefunction(fn):
+        raise TypeError(
+            "batch_filter called with async function. Use async_batch_filter."
+        )
+
+    results = batch_map(fn, items, **kwargs)
+    return [r.item for r in results if r.ok and r.value]
+
+
+async def async_batch_filter(
+    fn: Callable[..., bool],
+    items: Iterable[Any],
+    **kwargs,
+) -> list:
+    """Async version of batch_filter."""
+    results = await async_batch_map(fn, items, **kwargs)
+    return [r.item for r in results if r.ok and r.value]

batchly/foreach.py

@@ -0,0 +1,31 @@
+"""batch_for_each implementation."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Iterable
+
+from .map_ import batch_map, async_batch_map
+
+
+def batch_for_each(
+    fn: Callable[..., Any],
+    items: Iterable[Any],
+    **kwargs,
+) -> None:
+    """Apply fn to each item (side effects only), processing in parallel."""
+    if inspect.iscoroutinefunction(fn):
+        raise TypeError(
+            "batch_for_each called with async function. Use async_batch_for_each."
+        )
+
+    batch_map(fn, items, **kwargs)
+
+
+async def async_batch_for_each(
+    fn: Callable[..., Any],
+    items: Iterable[Any],
+    **kwargs,
+) -> None:
+    """Async version of batch_for_each."""
+    await async_batch_map(fn, items, **kwargs)

batchly/map_.py

@@ -0,0 +1,461 @@
+"""batch_map implementation — parallel map with all options."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Callable, Generator, Iterable, AsyncGenerator
+
+from .errors import BatchError, TimeoutError
+from .progress import ProgressInfo
+from .rate_limit import RateLimiter
+from .result import BatchResult
+from .retry import async_retry_call, retry_call
+
+
+def batch_map(
+    fn: Callable[..., Any],
+    items: Iterable[Any],
+    *,
+    max_workers: int = 4,
+    retries: int = 0,
+    backoff: str = "exponential",
+    retry_on: tuple[type[Exception], ...] = (Exception,),
+    on_error: str = "skip",
+    chunk_size: int | None = None,
+    rate_limit: int | None = None,
+    ordered: bool = True,
+    timeout: float | None = None,
+    stream: bool = False,
+    progress: Callable[[ProgressInfo], None] | None = None,
+) -> list[BatchResult] | Generator[BatchResult, None, None]:
+    """Map function over items in parallel."""
+    items = list(items)
+
+    if inspect.iscoroutinefunction(fn):
+        raise TypeError(
+            "batch_map called with async function but not awaited. "
+            "Use: results = await async_batch_map(fn, items, ...)"
+        )
+
+    if stream:
+        return _stream_sync(
+            fn, items,
+            max_workers=max_workers, retries=retries, backoff=backoff,
+            retry_on=retry_on, on_error=on_error, chunk_size=chunk_size,
+            rate_limit=rate_limit, timeout=timeout, progress=progress,
+        )
+
+    return _map_sync(
+        fn, items,
+        max_workers=max_workers, retries=retries, backoff=backoff,
+        retry_on=retry_on, on_error=on_error, chunk_size=chunk_size,
+        rate_limit=rate_limit, ordered=ordered, timeout=timeout, progress=progress,
+    )
+
+
+async def async_batch_map(
+    fn: Callable[..., Any],
+    items: Iterable[Any],
+    *,
+    max_workers: int = 4,
+    retries: int = 0,
+    backoff: str = "exponential",
+    retry_on: tuple[type[Exception], ...] = (Exception,),
+    on_error: str = "skip",
+    chunk_size: int | None = None,
+    rate_limit: int | None = None,
+    ordered: bool = True,
+    timeout: float | None = None,
+    stream: bool = False,
+    progress: Callable[[ProgressInfo], None] | None = None,
+) -> list[BatchResult] | AsyncGenerator[BatchResult, None]:
+    """Async version of batch_map."""
+    if stream:
+        return _async_stream(
+            fn, list(items),
+            max_workers=max_workers, retries=retries, backoff=backoff,
+            retry_on=retry_on, on_error=on_error, chunk_size=chunk_size,
+            rate_limit=rate_limit, timeout=timeout, progress=progress,
+        )
+
+    return await _async_map(
+        fn, list(items),
+        max_workers=max_workers, retries=retries, backoff=backoff,
+        retry_on=retry_on, on_error=on_error, chunk_size=chunk_size,
+        rate_limit=rate_limit, ordered=ordered, timeout=timeout, progress=progress,
+    )
+
+
+async def _async_map(
+    fn, items, *,
+    max_workers=4, retries=0, backoff="exponential",
+    retry_on=(Exception,), on_error="skip",
+    chunk_size=None, rate_limit=None,
+    ordered=True, timeout=None, progress=None,
+) -> list[BatchResult]:
+    """Async batch map that returns a list."""
+    limiter = RateLimiter(rate_limit) if rate_limit else None
+
+    if chunk_size is not None:
+        chunks = [items[i:i + chunk_size] for i in range(0, len(items), chunk_size)]
+        total_tasks = len(chunks)
+        item_mapping = list(enumerate(chunks))
+    else:
+        total_tasks = len(items)
+        item_mapping = list(enumerate(items))
+
+    start = time.monotonic()
+    completed = 0
+    results = [None] * total_tasks
+    semaphore = asyncio.Semaphore(max_workers)
+
+    async def _process_task(task_idx: int, item: Any):
+        nonlocal completed
+        async with semaphore:
+            if limiter:
+                await limiter.async_acquire()
+            t0 = time.monotonic()
+
+            args = (item,) if chunk_size is None else ()
+            kw = {"chunk": item} if chunk_size is not None else {}
+
+            try:
+                if timeout is not None:
+                    val, err = await asyncio.wait_for(
+                        async_retry_call(fn, args=args, kwargs=kw,
+                                          retries=retries, backoff=backoff,
+                                          retry_on=retry_on, rate_limiter=None),
+                        timeout=timeout,
+                    )
+                else:
+                    val, err = await async_retry_call(
+                        fn, args=args, kwargs=kw,
+                        retries=retries, backoff=backoff,
+                        retry_on=retry_on, rate_limiter=None,
+                    )
+            except asyncio.TimeoutError as e:
+                if on_error == "raise":
+                    raise TimeoutError(f"Timed out: {item}", item=item, original_error=e)
+                elif on_error == "collect":
+                    err = e
+                    val = None
+                else:
+                    completed += 1
+                    if progress:
+                        elapsed = time.monotonic() - start
+                        eta = (elapsed / completed * (total_tasks - completed)) if completed > 0 else 0
+                        progress(ProgressInfo(completed=completed, total=total_tasks, elapsed=elapsed, eta=eta))
+                    return task_idx, None
+
+            duration = time.monotonic() - t0
+
+            if err is not None:
+                if on_error == "raise":
+                    raise BatchError(f"Failed: {item}", item=item, original_error=err)
+                elif on_error == "collect":
+                    br = BatchResult(value=None, error=err, item=item, duration=duration)
+                else:
+                    br = None
+            else:
+                br = BatchResult(value=val, error=None, item=item, duration=duration)
+
+            completed += 1
+            if progress:
+                elapsed = time.monotonic() - start
+                eta = (elapsed / completed * (total_tasks - completed)) if completed > 0 else 0
+                progress(ProgressInfo(completed=completed, total=total_tasks, elapsed=elapsed, eta=eta))
+
+            return task_idx, br
+
+    coros = [_process_task(idx, item) for idx, item in item_mapping]
+    gathered = await asyncio.gather(*coros, return_exceptions=True)
+
+    for i, result in enumerate(gathered):
+        if isinstance(result, Exception):
+            if on_error == "raise":
+                raise result
+            continue
+        task_idx, br = result
+        if br is not None and ordered:
+            results[task_idx] = br
+        elif br is not None:
+            results.append(br)
+
+    if on_error in ("skip", "collect"):
+        results = [r for r in results if r is not None]
+
+    return results
+
+
+async def _async_stream(
+    fn, items, *,
+    max_workers=4, retries=0, backoff="exponential",
+    retry_on=(Exception,), on_error="skip",
+    chunk_size=None, rate_limit=None,
+    timeout=None, progress=None,
+) -> AsyncGenerator[BatchResult, None]:
+    """Async streaming batch map — yields results as they complete."""
+    limiter = RateLimiter(rate_limit) if rate_limit else None
+
+    if chunk_size is not None:
+        chunks = [items[i:i + chunk_size] for i in range(0, len(items), chunk_size)]
+        total_tasks = len(chunks)
+        item_mapping = list(enumerate(chunks))
+    else:
+        total_tasks = len(items)
+        item_mapping = list(enumerate(items))
+
+    start = time.monotonic()
+    completed = 0
+    semaphore = asyncio.Semaphore(max_workers)
+
+    async def _process_task(task_idx: int, item: Any):
+        nonlocal completed
+        async with semaphore:
+            if limiter:
+                await limiter.async_acquire()
+            t0 = time.monotonic()
+
+            args = (item,) if chunk_size is None else ()
+            kw = {"chunk": item} if chunk_size is not None else {}
+
+            try:
+                if timeout is not None:
+                    val, err = await asyncio.wait_for(
+                        async_retry_call(fn, args=args, kwargs=kw,
+                                          retries=retries, backoff=backoff,
+                                          retry_on=retry_on, rate_limiter=None),
+                        timeout=timeout,
+                    )
+                else:
+                    val, err = await async_retry_call(
+                        fn, args=args, kwargs=kw,
+                        retries=retries, backoff=backoff,
+                        retry_on=retry_on, rate_limiter=None,
+                    )
+            except asyncio.TimeoutError as e:
+                if on_error == "raise":
+                    raise TimeoutError(f"Timed out: {item}", item=item, original_error=e)
+                elif on_error == "collect":
+                    err = e
+                    val = None
+                else:
+                    completed += 1
+                    if progress:
+                        elapsed = time.monotonic() - start
+                        eta = (elapsed / completed * (total_tasks - completed)) if completed > 0 else 0
+                        progress(ProgressInfo(completed=completed, total=total_tasks, elapsed=elapsed, eta=eta))
+                    return task_idx, None
+
+            duration = time.monotonic() - t0
+
+            if err is not None:
+                if on_error == "raise":
+                    raise BatchError(f"Failed: {item}", item=item, original_error=err)
+                elif on_error == "collect":
+                    br = BatchResult(value=None, error=err, item=item, duration=duration)
+                else:
+                    br = None
+            else:
+                br = BatchResult(value=val, error=None, item=item, duration=duration)
+
+            completed += 1
+            if progress:
+                elapsed = time.monotonic() - start
+                eta = (elapsed / completed * (total_tasks - completed)) if completed > 0 else 0
+                progress(ProgressInfo(completed=completed, total=total_tasks, elapsed=elapsed, eta=eta))
+
+            return task_idx, br
+
+    coros = [_process_task(idx, item) for idx, item in item_mapping]
+    for coro in asyncio.as_completed(coros):
+        task_idx, br = await coro
+        if br is not None:
+            yield br
+
+
+def _takes_chunk(fn) -> bool:
+    import inspect
+    sig = inspect.signature(fn)
+    return 'chunk' in sig.parameters
+
+
+def _takes_items(fn) -> bool:
+    import inspect
+    sig = inspect.signature(fn)
+    return 'items' in sig.parameters
+
+
+def _map_sync(
+    fn, items, *,
+    max_workers=4, retries=0, backoff="exponential",
+    retry_on=(Exception,), on_error="skip",
+    chunk_size=None, rate_limit=None,
+    ordered=True, timeout=None, progress=None,
+) -> list[BatchResult]:
+    """Synchronous batch map."""
+    limiter = RateLimiter(rate_limit) if rate_limit else None
+
+    if chunk_size is not None:
+        chunks = [items[i:i + chunk_size] for i in range(0, len(items), chunk_size)]
+        work_items = list(enumerate(chunks))
+    else:
+        work_items = list(enumerate(items))
+
+    total = len(work_items)
+    results = [None] * total
+    completed = 0
+    start = time.monotonic()
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {}
+        for idx, item in work_items:
+            future = executor.submit(
+                _process_single,
+                fn, item, idx,
+                chunk_size=chunk_size, retries=retries,
+                backoff=backoff, retry_on=retry_on,
+                rate_limiter=limiter, timeout=timeout,
+            )
+            futures[future] = idx
+
+        for future in as_completed(futures):
+            idx = futures[future]
+            try:
+                br = future.result()
+            except BatchError as e:
+                if on_error == "raise":
+                    raise
+                if on_error == "collect":
+                    br = BatchResult(value=None, error=e.original_error or e, item=e.item, duration=0)
+                else:
+                    br = None
+            except Exception as e:
+                if on_error == "raise":
+                    raise
+                if on_error == "collect":
+                    br = BatchResult(value=None, error=e, item=work_items[idx][1], duration=0)
+                else:
+                    br = None
+
+            if br is not None:
+                results[idx] = br
+
+            completed += 1
+            if progress:
+                elapsed = time.monotonic() - start
+                eta = (elapsed / completed * (total - completed)) if completed > 0 else 0
+                progress(ProgressInfo(completed=completed, total=total, elapsed=elapsed, eta=eta))
+
+    if on_error in ("skip", "collect"):
+        results = [r for r in results if r is not None]
+
+    return results
+
+
+def _stream_sync(
+    fn, items, *,
+    max_workers=4, retries=0, backoff="exponential",
+    retry_on=(Exception,), on_error="skip",
+    chunk_size=None, rate_limit=None,
+    timeout=None, progress=None,
+) -> Generator[BatchResult, None, None]:
+    """Streaming sync batch map — yields results as they complete."""
+    limiter = RateLimiter(rate_limit) if rate_limit else None
+
+    if chunk_size is not None:
+        chunks = [items[i:i + chunk_size] for i in range(0, len(items), chunk_size)]
+        work_items = list(enumerate(chunks))
+    else:
+        work_items = list(enumerate(items))
+
+    total = len(work_items)
+    completed = 0
+    start = time.monotonic()
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {}
+        for idx, item in work_items:
+            future = executor.submit(
+                _process_single,
+                fn, item, idx,
+                chunk_size=chunk_size, retries=retries,
+                backoff=backoff, retry_on=retry_on,
+                rate_limiter=limiter, timeout=timeout,
+            )
+            futures[future] = idx
+
+        for future in as_completed(futures):
+            idx = futures[future]
+            try:
+                br = future.result()
+            except BatchError as e:
+                if on_error == "raise":
+                    raise
+                if on_error == "collect":
+                    br = BatchResult(value=None, error=e.original_error or e, item=e.item, duration=0)
+                else:
+                    br = None
+            except Exception as e:
+                if on_error == "raise":
+                    raise
+                if on_error == "collect":
+                    br = BatchResult(value=None, error=e, item=work_items[idx][1], duration=0)
+                else:
+                    br = None
+
+            completed += 1
+            if progress:
+                elapsed = time.monotonic() - start
+                eta = (elapsed / completed * (total - completed)) if completed > 0 else 0
+                progress(ProgressInfo(completed=completed, total=total, elapsed=elapsed, eta=eta))
+
+            if br is not None:
+                yield br
+
+
+def _process_single(fn, item, idx, *, chunk_size=None, retries=0,
+                    backoff="exponential", retry_on=(Exception,),
+                    rate_limiter=None, timeout=None):
+    """Process a single item with retries, rate limiting, and timeout."""
+    if chunk_size is not None:
+        args = ()
+        kwargs = {"chunk": item}
+    else:
+        args = (item,)
+        kwargs = {}
+
+    if timeout is not None:
+        from concurrent.futures import ThreadPoolExecutor as TPE, TimeoutError as FuturesTimeout
+        tpe = TPE(max_workers=1)
+        future = tpe.submit(
+            retry_call, fn, args=args, kwargs=kwargs,
+            retries=retries, backoff=backoff, retry_on=retry_on,
+            rate_limiter=rate_limiter,
+        )
+        try:
+            val, err = future.result(timeout=timeout)
+        except FuturesTimeout:
+            future.cancel()
+            tpe.shutdown(wait=False, cancel_futures=True)
+            raise TimeoutError(
+                f"Item {item} timed out after {timeout}s",
+                item=item,
+                original_error=FuturesTimeout(f"Timed out after {timeout}s"),
+            )
+        finally:
+            tpe.shutdown(wait=False)
+    else:
+        val, err = retry_call(
+            fn, args=args, kwargs=kwargs,
+            retries=retries, backoff=backoff, retry_on=retry_on,
+            rate_limiter=rate_limiter,
+        )
+
+    if err is not None:
+        raise BatchError(f"Failed processing item: {item}", item=item, original_error=err)
+
+    return BatchResult(value=val, error=None, item=item, duration=0)

batchly/progress.py

@@ -0,0 +1,73 @@
+"""Progress tracking for batch operations."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class ProgressInfo:
+    """Progress information passed to callbacks."""
+
+    completed: int = 0
+    total: int = 0
+    elapsed: float = 0.0
+    eta: float = 0.0
+
+    @property
+    def pct(self) -> float:
+        if self.total == 0:
+            return 0.0
+        return self.completed / self.total * 100.0
+
+    @property
+    def rate(self) -> float:
+        if self.elapsed == 0:
+            return 0.0
+        return self.completed / self.elapsed
+
+
+class ProgressBar:
+    """Terminal progress bar.
+
+    Usage:
+        results = batch_map(fn, items, progress=ProgressBar())
+    """
+
+    def __init__(self, width: int = 40, file=None):
+        self.width = width
+        self._file = file or sys.stderr
+        self._lock = threading.Lock()
+        self._start = time.monotonic()
+
+    def __call__(self, info: ProgressInfo) -> None:
+        pct = info.pct
+        filled = int(self.width * pct / 100)
+        bar = "█" * filled + "░" * (self.width - filled)
+        elapsed = info.elapsed
+        eta = info.eta
+        if eta >= 60:
+            eta_str = f"{eta / 60:.1f}m"
+        elif eta > 0:
+            eta_str = f"{eta:.1f}s"
+        else:
+            eta_str = "—"
+        if elapsed >= 60:
+            elapsed_str = f"{elapsed / 60:.1f}m"
+        else:
+            elapsed_str = f"{elapsed:.1f}s"
+
+        line = f"\r[{bar}] {pct:5.1f}% ({info.completed}/{info.total}) {elapsed_str} elapsed, {eta_str} remaining"
+        with self._lock:
+            self._file.write(line)
+            self._file.flush()
+            if info.completed >= info.total and info.total > 0:
+                self._file.write("\n")
+                self._file.flush()
+
+    def reset(self) -> None:
+        self._start = time.monotonic()

batchly/rate_limit.py

@@ -0,0 +1,60 @@
+"""Token bucket rate limiter."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+
+class RateLimiter:
+    """Token bucket rate limiter.
+
+    Args:
+        max_per_second: Maximum number of tokens (calls) per second.
+    """
+
+    def __init__(self, max_per_second: int):
+        self.max_per_second = max_per_second
+        self._tokens = float(max_per_second)
+        self._last_refill = time.monotonic()
+        self._lock = threading.Lock()
+        self._min_interval = 1.0 / max_per_second
+
+    def acquire(self) -> None:
+        """Block until a token is available."""
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._last_refill
+                self._tokens += elapsed * self.max_per_second
+                if self._tokens > self.max_per_second:
+                    self._tokens = float(self.max_per_second)
+                self._last_refill = now
+
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                # Calculate wait time
+                wait = (1.0 - self._tokens) / self.max_per_second
+
+            time.sleep(wait)
+
+    async def async_acquire(self) -> None:
+        """Async version of acquire."""
+        import asyncio
+
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._last_refill
+                self._tokens += elapsed * self.max_per_second
+                if self._tokens > self.max_per_second:
+                    self._tokens = float(self.max_per_second)
+                self._last_refill = now
+
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                wait = (1.0 - self._tokens) / self.max_per_second
+
+            await asyncio.sleep(wait)

batchly/result.py

@@ -0,0 +1,28 @@
+"""Result wrapper for batch operations."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class BatchResult(Generic[T]):
+    """Wraps the result of processing a single item."""
+
+    value: T | None = None
+    error: Exception | None = None
+    item: Any = None
+    duration: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    def unwrap(self) -> T:
+        if self.error is not None:
+            raise self.error
+        return self.value

batchly/retry.py

@@ -0,0 +1,80 @@
+"""Retry logic with backoff strategies."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Callable
+
+
+def _compute_backoff(attempt: int, strategy: str, base: float = 1.0) -> float:
+    """Compute backoff delay in seconds."""
+    if strategy == "fixed":
+        return base
+    elif strategy == "exponential":
+        return base * (2 ** (attempt - 1)) + random.uniform(0, 0.1)
+    elif strategy == "adaptive":
+        return min(base * (2 ** (attempt - 1)), 60.0) + random.uniform(0, 0.1)
+    else:
+        return base
+
+
+def retry_call(
+    fn: Callable[..., Any],
+    args: tuple = (),
+    kwargs: dict | None = None,
+    retries: int = 0,
+    backoff: str = "exponential",
+    retry_on: tuple[type[Exception], ...] = (Exception,),
+    rate_limiter=None,
+) -> Any:
+    """Call fn with retry logic.
+
+    Returns (result, error) tuple. error is None on success.
+    """
+    last_error = None
+    for attempt in range(retries + 1):
+        if rate_limiter is not None:
+            rate_limiter.acquire()
+        try:
+            return fn(*args, **(kwargs or {})), None
+        except retry_on as e:
+            last_error = e
+            if attempt < retries:
+                delay = _compute_backoff(attempt + 1, backoff)
+                time.sleep(delay)
+            else:
+                return None, e
+        except Exception as e:
+            return None, e
+    return None, last_error
+
+
+async def async_retry_call(
+    fn: Callable[..., Any],
+    args: tuple = (),
+    kwargs: dict | None = None,
+    retries: int = 0,
+    backoff: str = "exponential",
+    retry_on: tuple[type[Exception], ...] = (Exception,),
+    rate_limiter=None,
+) -> tuple[Any, Exception | None]:
+    """Async version of retry_call."""
+    import asyncio
+
+    last_error = None
+    for attempt in range(retries + 1):
+        if rate_limiter is not None:
+            await rate_limiter.async_acquire()
+        try:
+            return await fn(*args, **(kwargs or {})), None
+        except retry_on as e:
+            last_error = e
+            if attempt < retries:
+                delay = _compute_backoff(attempt + 1, backoff)
+                await asyncio.sleep(delay)
+            else:
+                return None, e
+        except Exception as e:
+            return None, e
+    return None, last_error

batchly-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: batchly
+Version: 0.1.0
+Summary: Batch processing made simple — concurrency, retries, progress, and error handling
+Author: Teja
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"

batchly-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+batchly/__init__.py,sha256=UqmQg7UOqEzQNZicgcP_elJiFMLqfTPDGJKp6UgCsHE,713
+batchly/batch.py,sha256=FqCj_L_k-5n-1GwqPXNoUaQyIJWLRXdAGFIZg8FkX-Y,4486
+batchly/errors.py,sha256=qFZTk0Of9ZE1jlk-SZ_OY0Ui3XoN57AOL7mM2V9VLq0,410
+batchly/filter_.py,sha256=aGkMh6uu-wQ8lRg_H0kGrLP-KbWax7iIK5Lg5-0H42I,945
+batchly/foreach.py,sha256=N6uCj8QQ-YcJzmBH58dMdeRiJ8io8tPyBZNJTiU2HRY,753
+batchly/map_.py,sha256=EFBi16k04vhCNlov3Zc1Ly2dZwn0rhRnSxi3iZfjf_Y,16692
+batchly/progress.py,sha256=PrmKOVthVhX_UArNsJYYSgfxHPkz4nh7_FicWbwAfgY,1935
+batchly/rate_limit.py,sha256=tIPMC32hKHNk8U8coYMcXmAAqBvL6c2wMQAgniPaZrM,1868
+batchly/result.py,sha256=KGUC0p7MmcIthCFlmEs38lf6wv2RTsx6rn5GSua_a3o,595
+batchly/retry.py,sha256=OcszoLZXiGY_ZeQEJK54nfMWTt7u8IXYKOpzd1prRWE,2322
+batchly-0.1.0.dist-info/METADATA,sha256=dK1-5S00Uvq2J_yNMpiWWyMZfm8JZqtdHruLuD_5toU,387
+batchly-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+batchly-0.1.0.dist-info/top_level.txt,sha256=lcpXnKXKuPFalW1pqVpYhPphM9xgVa-OHyUilnvFDug,8
+batchly-0.1.0.dist-info/RECORD,,

batchly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

batchly-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+batchly