pyarallel 0.3.0__tar.gz → 0.6.0__tar.gz

pyarallel-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --group dev
+      - name: Lint
+        run: |
+          uv run ruff check pyarallel tests
+          uv run ruff format --check pyarallel tests
+      - name: Type check (strict, package + typing assertions)
+        run: uv run mypy pyarallel tests/typing_assertions.py
+      - name: Tests
+        run: uv run pytest -q
+      - name: Docs (strict)
+        run: uv run mkdocs build --strict

pyarallel-0.6.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 0.6.0 — 2026-07-06
+
+**One engine for every execution path.** All collected maps — sync and
+async — now run through the same windowed engine that streaming and
+`max_errors` already used. Behavior changes (pre-1.0, no deprecation
+cycle):
+
+- `batch_size` means one thing everywhere: the in-flight admission
+  window (default `2 × workers` sync, `2 × concurrency` async). Chunk
+  barriers no longer exist anywhere — a slow item never stalls the
+  items behind it.
+- Collected maps consume input lazily, one window ahead — generators
+  are never materialized. The plain no-kwargs call moves from eager
+  upfront submission to windowed admission (benchmarked: parity on
+  ms-scale tasks; see the v0.6 plan for numbers).
+- No-drain on stop, everywhere: after a timeout or abort the source
+  iterator is never touched again. Unsized inputs return a *shorter*
+  result instead of drained-and-appended failure placeholders.
+- New: `ParallelResult.timed_out` / `.aborted` report how the run ended
+  (at most one is set — first stop reason wins; both show up in the
+  repr). This is the reliable truncation signal for unsized inputs,
+  where a timed-out run can contain only successes.
+- `on_progress` with unsized inputs reports items *admitted* so far as
+  `total` (previously the final total, because input was materialized).
+  Pass a sized input for a real total.
+- Source-iterator errors surface mid-run instead of at materialization,
+  and propagate promptly: queued work is cancelled, but sync tasks
+  already running cannot be interrupted and may complete — side effects
+  included — in the background. Materialize the input first
+  (`list(items)`) if you need no-work-after-error guarantees, or use
+  the async API (tasks are cancelled and awaited).
+- Exception shape: errors raised from callbacks on the async plain path
+  propagate plain — the `ExceptionGroup` wrapper went away with the
+  removed `asyncio.TaskGroup`.
+- `parallel_starmap` no longer materializes its input — generators of
+  argument tuples stay lazy.
+- Total `timeout=` now binds during cached checkpoint admission too: a
+  checkpoint-heavy run can no longer overrun the deadline unnoticed.
+- Fixed: a `TimeoutError` raised by the source iterable itself is an
+  input error and propagates — it is no longer repackaged as deadline
+  expiry.
+
+Full contract and review history:
+[v0.6 Engine Unification Plan](docs/development/plans/v0.6-engine-unification.md).
+
+## 0.5.0 — 2026-07-05
+
+Structural quality: sliding-window streaming (`ordered=True`, streaming
+`on_progress`), `max_errors` early abort, `ItemResult.attempts`/
+`.duration`, `ParallelResult.ok_values()`, `checkpoint_key=` (schema v2),
+`sequential=True` debug mode, async total `timeout=`, contextvars
+propagation, `worker_init=`/`max_tasks_per_worker=`, typed decorator
+options via `Unpack[TypedDict]`. Details:
+[v0.5.0 Plan](docs/development/plans/v0.5.0.md). Not published to PyPI.
+
+## 0.4.0 — 2026-06
+
+Repositioned as the fan-out layer for rate-limited APIs: server-driven
+backoff (`retry_if`/`wait_from`), shareable `Limiter`, real token bucket
+(`burst=`), `checkpoint=` resume, strict typing. Tag only, not published.

{pyarallel-0.3.0 → pyarallel-0.6.0}/Makefile

@@ -18,7 +18,6 @@ docs-serve:
 	uv run mkdocs serve
 
 docs-deploy:
-	uv run python -c "import pyarallel; from pathlib import Path; yml = Path('mkdocs.yml').read_text(); Path('mkdocs.yml').write_text(yml.replace('version: .*', f'version: {pyarallel.__version__}'))"
 	uv run mkdocs gh-deploy
 
 format:
@@ -27,7 +26,7 @@ format:
 
 lint:
 	uv run ruff check .
-	uv run mypy pyarallel/
+	uv run mypy pyarallel/ tests/typing_assertions.py
 
 clean:
 	rm -rf build/

{pyarallel-0.3.0 → pyarallel-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pyarallel
-Version: 0.3.0
-Summary: A powerful parallel execution library for Python
+Version: 0.6.0
+Summary: The fan-out layer for rate-limited APIs — parallel map with rate limiting, retry, and structured errors. Sync and async, zero dependencies.
 Project-URL: Homepage, https://github.com/oneryalcin/pyarallel
 Project-URL: Repository, https://github.com/oneryalcin/pyarallel.git
 Project-URL: Documentation, https://oneryalcin.github.io/pyarallel
@@ -41,9 +41,9 @@ Description-Content-Type: text/markdown
 
 [![PyPI version](https://img.shields.io/pypi/v/pyarallel)](https://pypi.org/project/pyarallel/) [![PyPI Downloads](https://static.pepy.tech/badge/pyarallel/month)](https://pepy.tech/project/pyarallel)
 
-Apply one function to many inputs — with rate limiting, retry, batching, and structured errors. Sync and async.
+The fan-out layer for rate-limited APIs. Apply one function to many inputs — with rate limiting, retry, resume, and structured errors. Sync and async.
 
-Pyarallel is for "fan out one function over N items" workloads: API calls, file processing, data crunching. Not DAGs, not queues, not distributed systems. Just `concurrent.futures` and `asyncio` with the common policies and result handling already built in.
+Pyarallel is for "fan out one function over N items" workloads against services that throttle you: LLM calls, embeddings, scraping, SaaS APIs — plus general file processing and data crunching. Everyone hand-rolls the same stack for this: a semaphore, tenacity, a rate limiter, ad-hoc 429 handling. Pyarallel is that stack as one coherent tool. Not DAGs, not queues, not distributed systems. Just `concurrent.futures` and `asyncio` with the policies and result handling already built in.
 
 **Zero dependencies. Python 3.12+.**
 
@@ -74,7 +74,7 @@ with ThreadPoolExecutor(max_workers=10) as pool:
         except Exception as e:
             errors.append((i, e))
 
-# No rate limiting. No retry. No batching. And you still
+# No rate limiting. No retry. No resume. And you still
 # need to wire those yourself every time.
 ```
 
@@ -123,15 +123,21 @@ pip install pyarallel
 
 ## What You Get
 
-- **Rate limiting** — token bucket, per-second/minute/hour: `rate_limit=RateLimit(100, "minute")`
+- **Rate limiting** — token bucket with burst, per-second/minute/hour: `rate_limit=RateLimit(100, "minute", burst=20)`
+- **Shared quota** — one `Limiter` instance across calls and functions when the budget belongs to an API key: `rate_limit=Limiter(RateLimit(100, "minute"))`
 - **Retry with backoff** — per-item, exponential, jitter, exception filtering: `retry=Retry(attempts=3, on=(ConnectionError,))`
-- **Batched execution** — lazy input consumption for generators, memory control: `batch_size=500`
-- **Streaming** — constant-memory processing via `parallel_iter` / `async_parallel_iter`
-- **Structured errors** — `ParallelResult` with `.ok`, `.successes()`, `.failures()`, `.raise_on_failure()`
-- **Timeouts** — wall-clock for the whole operation (`timeout=30.0`) or per-task in async (`task_timeout=5.0`)
-- **Progress callbacks** — `on_progress=lambda done, total: print(f"{done}/{total}")`
-- **Process executor** — CPU-bound work: `executor="process"`
-- **Decorator API** — `@parallel` / `@async_parallel` with `.map()`, `.starmap()`, `.stream()`
+- **Server-driven backoff** — honor 429 + `Retry-After`: `retry=Retry(retry_if=..., wait_from=...)`; the wait also pauses the shared limiter so one throttled task slows the whole pool
+- **Checkpoint/resume** — `checkpoint="run.ckpt"`: a crash at item 40,000 resumes instead of restarting from zero; `checkpoint_key=lambda u: u.id` keys rows by identity so evolving inputs keep completed work
+- **Early abort** — `max_errors=10`: a dead API costs tens of calls, not thousands; unrun items are marked `Aborted`, partial results returned
+- **One windowed engine** — every API (collected and streaming, sync and async) admits work through a bounded in-flight window: lazy input, generators never materialized, no batch barriers, a straggler never stalls the items behind it
+- **Streaming** — `parallel_iter` / `async_parallel_iter`: `ordered=True` for input-order yields, per-item `attempts`/`duration`
+- **Structured errors** — `ParallelResult` with `.ok`, `.ok_values()`, `.successes()`, `.failures()`, `.raise_on_failure()`, plus `.timed_out`/`.aborted` for how the run ended
+- **Timeouts** — total wall-clock on sync *and* async (`timeout=30.0`), per-task in async (`task_timeout=5.0`)
+- **Debug mode** — `sequential=True` runs inline: no pool, real stack traces, working breakpoints
+- **Progress callbacks** — `on_progress=lambda done, total: print(f"{done}/{total}")` on collected and streaming APIs
+- **Process executor** — CPU-bound work: `executor="process"`, with `worker_init=` and `max_tasks_per_worker=`
+- **Contextvars propagation** — correlation IDs survive into thread workers
+- **Decorator API** — `@parallel` / `@async_parallel` with `.map()`, `.starmap()`, `.stream()` — fully typed via `Unpack[TypedDict]`
 
 ## Quick Start
 
@@ -254,8 +260,10 @@ Async mirrors: `async_parallel_map`, `async_parallel_starmap`, `async_parallel_i
 
 | Config | Example |
 |---|---|
-| `RateLimit(count, per)` | `RateLimit(100, "minute")` |
-| `Retry(attempts, backoff, on)` | `Retry(attempts=3, on=(ConnectionError,))` |
+| `RateLimit(count, per, burst)` | `RateLimit(100, "minute", burst=20)` |
+| `Limiter(rate_limit)` | shared budget: `Limiter(RateLimit(100, "minute"))` |
+| `Retry(attempts, backoff, on, retry_if, wait_from)` | `Retry(attempts=3, on=(ConnectionError,))` |
+| `checkpoint=` | resumable runs: `checkpoint="run.ckpt"` |
 
 Works with instance methods and static methods via `@parallel` decorator — see [full docs](https://oneryalcin.github.io/pyarallel/).
 

{pyarallel-0.3.0 → pyarallel-0.6.0}/README.md

@@ -2,9 +2,9 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/pyarallel)](https://pypi.org/project/pyarallel/) [![PyPI Downloads](https://static.pepy.tech/badge/pyarallel/month)](https://pepy.tech/project/pyarallel)
 
-Apply one function to many inputs — with rate limiting, retry, batching, and structured errors. Sync and async.
+The fan-out layer for rate-limited APIs. Apply one function to many inputs — with rate limiting, retry, resume, and structured errors. Sync and async.
 
-Pyarallel is for "fan out one function over N items" workloads: API calls, file processing, data crunching. Not DAGs, not queues, not distributed systems. Just `concurrent.futures` and `asyncio` with the common policies and result handling already built in.
+Pyarallel is for "fan out one function over N items" workloads against services that throttle you: LLM calls, embeddings, scraping, SaaS APIs — plus general file processing and data crunching. Everyone hand-rolls the same stack for this: a semaphore, tenacity, a rate limiter, ad-hoc 429 handling. Pyarallel is that stack as one coherent tool. Not DAGs, not queues, not distributed systems. Just `concurrent.futures` and `asyncio` with the policies and result handling already built in.
 
 **Zero dependencies. Python 3.12+.**
 
@@ -35,7 +35,7 @@ with ThreadPoolExecutor(max_workers=10) as pool:
         except Exception as e:
             errors.append((i, e))
 
-# No rate limiting. No retry. No batching. And you still
+# No rate limiting. No retry. No resume. And you still
 # need to wire those yourself every time.
 ```
 
@@ -84,15 +84,21 @@ pip install pyarallel
 
 ## What You Get
 
-- **Rate limiting** — token bucket, per-second/minute/hour: `rate_limit=RateLimit(100, "minute")`
+- **Rate limiting** — token bucket with burst, per-second/minute/hour: `rate_limit=RateLimit(100, "minute", burst=20)`
+- **Shared quota** — one `Limiter` instance across calls and functions when the budget belongs to an API key: `rate_limit=Limiter(RateLimit(100, "minute"))`
 - **Retry with backoff** — per-item, exponential, jitter, exception filtering: `retry=Retry(attempts=3, on=(ConnectionError,))`
-- **Batched execution** — lazy input consumption for generators, memory control: `batch_size=500`
-- **Streaming** — constant-memory processing via `parallel_iter` / `async_parallel_iter`
-- **Structured errors** — `ParallelResult` with `.ok`, `.successes()`, `.failures()`, `.raise_on_failure()`
-- **Timeouts** — wall-clock for the whole operation (`timeout=30.0`) or per-task in async (`task_timeout=5.0`)
-- **Progress callbacks** — `on_progress=lambda done, total: print(f"{done}/{total}")`
-- **Process executor** — CPU-bound work: `executor="process"`
-- **Decorator API** — `@parallel` / `@async_parallel` with `.map()`, `.starmap()`, `.stream()`
+- **Server-driven backoff** — honor 429 + `Retry-After`: `retry=Retry(retry_if=..., wait_from=...)`; the wait also pauses the shared limiter so one throttled task slows the whole pool
+- **Checkpoint/resume** — `checkpoint="run.ckpt"`: a crash at item 40,000 resumes instead of restarting from zero; `checkpoint_key=lambda u: u.id` keys rows by identity so evolving inputs keep completed work
+- **Early abort** — `max_errors=10`: a dead API costs tens of calls, not thousands; unrun items are marked `Aborted`, partial results returned
+- **One windowed engine** — every API (collected and streaming, sync and async) admits work through a bounded in-flight window: lazy input, generators never materialized, no batch barriers, a straggler never stalls the items behind it
+- **Streaming** — `parallel_iter` / `async_parallel_iter`: `ordered=True` for input-order yields, per-item `attempts`/`duration`
+- **Structured errors** — `ParallelResult` with `.ok`, `.ok_values()`, `.successes()`, `.failures()`, `.raise_on_failure()`, plus `.timed_out`/`.aborted` for how the run ended
+- **Timeouts** — total wall-clock on sync *and* async (`timeout=30.0`), per-task in async (`task_timeout=5.0`)
+- **Debug mode** — `sequential=True` runs inline: no pool, real stack traces, working breakpoints
+- **Progress callbacks** — `on_progress=lambda done, total: print(f"{done}/{total}")` on collected and streaming APIs
+- **Process executor** — CPU-bound work: `executor="process"`, with `worker_init=` and `max_tasks_per_worker=`
+- **Contextvars propagation** — correlation IDs survive into thread workers
+- **Decorator API** — `@parallel` / `@async_parallel` with `.map()`, `.starmap()`, `.stream()` — fully typed via `Unpack[TypedDict]`
 
 ## Quick Start
 
@@ -215,8 +221,10 @@ Async mirrors: `async_parallel_map`, `async_parallel_starmap`, `async_parallel_i
 
 | Config | Example |
 |---|---|
-| `RateLimit(count, per)` | `RateLimit(100, "minute")` |
-| `Retry(attempts, backoff, on)` | `Retry(attempts=3, on=(ConnectionError,))` |
+| `RateLimit(count, per, burst)` | `RateLimit(100, "minute", burst=20)` |
+| `Limiter(rate_limit)` | shared budget: `Limiter(RateLimit(100, "minute"))` |
+| `Retry(attempts, backoff, on, retry_if, wait_from)` | `Retry(attempts=3, on=(ConnectionError,))` |
+| `checkpoint=` | resumable runs: `checkpoint="run.ckpt"` |
 
 Works with instance methods and static methods via `@parallel` decorator — see [full docs](https://oneryalcin.github.io/pyarallel/).
 

{pyarallel-0.3.0 → pyarallel-0.6.0}/docs/api-reference/async.md

@@ -1,6 +1,6 @@
 # API Reference: Async
 
-Pyarallel provides async-native parallel execution using `asyncio.TaskGroup` for structured concurrency and `asyncio.Semaphore` for concurrency control.
+Pyarallel provides async-native parallel execution: a windowed engine driven by `asyncio.wait` with `asyncio.Semaphore` for concurrency control — in-flight tasks are cancelled and awaited on errors and timeouts, so nothing is left running on the loop.
 
 ## `async_parallel_map`
 
@@ -14,11 +14,15 @@ results = await async_parallel_map(
     items,                           # Any iterable
     *,
     concurrency=4,                   # Max concurrent tasks
-    rate_limit=None,                 # RateLimit or ops/second
-    task_timeout=None,                    # Per-task timeout in seconds
+    rate_limit=None,                 # RateLimit spec, shared Limiter, or ops/second
+    timeout=None,                    # Total wall-clock timeout (mirror of sync)
+    task_timeout=None,               # Per-task timeout in seconds
     on_progress=None,                # callback(completed, total)
     batch_size=None,                 # Lazy batch consumption for unsized iterables
     retry=None,                      # Retry(attempts=3, backoff=1.0)
+    checkpoint=None,                 # Path to a resume file (SQLite)
+    checkpoint_key=None,             # Stable per-item identity for resume
+    max_errors=None,                 # Abort after N failures
 )
 ```
 
@@ -31,11 +35,15 @@ results = await async_parallel_map(
 | `fn` | async `Callable` | required | Async function to apply to each item |
 | `items` | `Iterable` | required | Any iterable |
 | `concurrency` | `int` | `4` | Maximum concurrent tasks |
-| `rate_limit` | `RateLimit \| float \| None` | `None` | Rate limiting |
+| `rate_limit` | `Limiter \| RateLimit \| float \| None` | `None` | Rate limiting. Pass a shared `Limiter` to draw from one budget across calls |
+| `timeout` | `float \| None` | `None` | **Total** wall-clock timeout — mirror of the sync `timeout`. Unfinished tasks are cancelled, `result.timed_out` is set; sized slots are marked `TimeoutError`, unsized inputs return a shorter result (the source is never drained) |
 | `task_timeout` | `float \| None` | `None` | **Per-task** timeout in seconds |
-| `on_progress` | `Callable[[int, int], None] \| None` | `None` | Progress callback. For unsized iterables with batching, `total` is items seen so far |
-| `batch_size` | `int \| None` | `None` | Process items in chunks. With unsized iterables, input is consumed lazily one batch at a time |
+| `on_progress` | `Callable[[int, int], None] \| None` | `None` | Progress callback. For unsized iterables, `total` is items seen so far |
+| `batch_size` | `int \| None` | `None` | Admission window: max tasks created but unresolved (default `2 × concurrency`). A lookahead/memory bound, not a chunk size — no barriers, input consumed lazily |
 | `retry` | `Retry \| None` | `None` | Per-item retry with backoff |
+| `checkpoint` | `str \| Path \| None` | `None` | Checkpoint file for resumable runs — completed items load from disk on rerun |
+| `checkpoint_key` | `Callable[[T], str \| int \| bytes] \| None` | `None` | Stable per-item identity — see the [sync docs](core.md#checkpoint-resume) |
+| `max_errors` | `int \| None` | `None` | Abort after this many failures (counted after retries). Windowed admission makes the abort cheap; unrun items are marked `Aborted`, `result.aborted` is set — see the [sync docs](core.md#early-abort-with-max_errors) |
 
 ### Why `concurrency` instead of `workers`?
 
@@ -47,8 +55,12 @@ Pre-v1, Pyarallel keeps these names intentionally different. If you're moving fr
 
 ### Other Differences from Sync
 
-- `task_timeout` is **per-task** (via `asyncio.wait_for`), not total wall-clock like sync `timeout`
-- Uses `asyncio.TaskGroup` for structured concurrency — proper cleanup on errors
+- Both timeouts exist here: `timeout` is total wall-clock (same contract
+  as sync), `task_timeout` is per-task via `asyncio.wait_for` — the sync
+  API deliberately has no per-task timeout (threads can't be cancelled)
+- On errors and timeouts, in-flight tasks are cancelled and awaited —
+  proper cleanup, nothing left running on the loop
+- No `sequential=` — `concurrency=1` already serializes
 
 ### Examples
 
@@ -76,10 +88,10 @@ results = await async_parallel_map(
 When `items` has a known length, `on_progress(done, total)` reports the final
 total.
 
-When `items` is unsized (for example a generator) and `batch_size` is set,
-Pyarallel keeps input consumption lazy instead of materializing the full input
-up front. In that mode, `total` is the number of items discovered so far, not a
-guaranteed final total.
+When `items` is unsized (for example a generator), input consumption is
+lazy — one window ahead, never materialized — and `total` is the number
+of items *admitted* so far, growing as the run progresses: a percentage
+over it is meaningless. Pass a sized input for a real total.
 
 ---
 
@@ -102,7 +114,10 @@ Takes the same options as `async_parallel_map`. Also available as `.starmap()` o
 
 ## `async_parallel_iter`
 
-Async streaming — yields `ItemResult` in completion order. Constant memory.
+Async streaming — yields `ItemResult` in completion order. A bounded
+window of tasks is in flight at any moment (default `2 × concurrency`,
+override with `batch_size`): memory stays constant, input is consumed
+lazily, and a slow item delays only itself.
 
 ```python
 from pyarallel import async_parallel_iter
@@ -114,13 +129,39 @@ async for item in async_parallel_iter(fetch, urls, concurrency=10):
         log_error(item.index, item.error)
 ```
 
+!!! note "Changed in v0.5 (streaming) and v0.6 (everywhere)"
+    `batch_size` is an **in-flight bound**, not a chunk size — one
+    meaning across every API since v0.6: there are no barriers, and
+    input is never materialized.
+
+Takes the same `ordered=` and `on_progress=` options as `parallel_iter`:
+`ordered=True` yields in input order with a reorder buffer counted
+inside the window; `on_progress(done, total)` fires per completed item.
+
+To stop early, close the generator — unlike sync generators, a bare
+`break` does **not** finalize an async generator promptly (Python defers
+it to event-loop shutdown, so tasks keep running). Wrap the stream in
+`contextlib.aclosing`:
+
+```python
+from contextlib import aclosing
+
+async with aclosing(async_parallel_iter(fetch, urls)) as stream:
+    async for item in stream:
+        if enough(item):
+            break   # aclosing cancels in-flight tasks right here
+```
+
+Async tasks, unlike threads, are genuinely cancellable — once the
+generator is closed, in-flight work stops.
+
 Also available as `.stream()` on `@async_parallel` decorated functions:
 
 ```python
 @async_parallel(concurrency=10)
 async def fetch(url): ...
 
-async for item in fetch.stream(urls, batch_size=1000):
+async for item in fetch.stream(urls):
     if item.ok:
         await db.save(item.value)
     else:
@@ -143,7 +184,7 @@ async def fn(item): ...
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `concurrency` | `int` | `4` | Default concurrency for `.map()` |
-| `rate_limit` | `RateLimit \| float \| None` | `None` | Default rate limiting |
+| `rate_limit` | `Limiter \| RateLimit \| float \| None` | `None` | Default rate limiting |
 
 ### Usage