batchly 0.1.0__tar.gz

batchly-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,48 @@
+# batchly
+
+Batch processing made simple — concurrency, retries, progress, and error handling.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from batchly import batch, batch_map, batch_filter, batch_for_each
+
+# Decorator
+@batch(max_workers=10, retries=3)
+def process(item):
+    return item * 2
+
+results = process([1, 2, 3, 4, 5])
+
+# Functional
+results = batch_map(transform, items, max_workers=20, retries=3)
+keep = batch_filter(predicate, items, max_workers=10)
+batch_for_each(side_effect, items, max_workers=5)
+
+# Reusable context
+b = Batch(max_workers=10, retries=3, progress=ProgressBar())
+results = b.map(fn, items)
+filtered = b.filter(pred, results)
+b.foreach(save, filtered)
+```
+
+## Features
+
+- **Concurrency** — ThreadPoolExecutor for sync, asyncio for async
+- **Retries** — Exponential/fixed/adaptive backoff
+- **Error handling** — skip, raise, or collect errors
+- **Rate limiting** — Token bucket algorithm
+- **Progress** — Built-in ProgressBar or custom callbacks
+- **Timeouts** — Per-item timeout support
+- **Chunked** — Group items for bulk processing
+- **Ordered** — Results match input order
+- **Streaming** — Generator mode for results as they complete
+- **Zero dependencies** — stdlib only
+
+MIT License.

batchly-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "batchly"
+version = "0.1.0"
+description = "Batch processing made simple — concurrency, retries, progress, and error handling"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Teja"}]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "hypothesis", "pytest-cov", "pytest-asyncio"]
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

batchly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

batchly-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)