pyarallel 0.1.3__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.1.3 → pyarallel-0.6.0}/.gitignore

@@ -44,5 +44,12 @@ htmlcov/
 *.log
 
 
-# docs 
-site
+# docs
+site
+
+# Claude Code / local dev
+CLAUDE.md
+AGENTS.md
+.omx/
+interim-feedback.md
+pain_points.md

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.1.3 → pyarallel-0.6.0}/CONTRIBUTING.md

@@ -40,15 +40,16 @@ We use GitHub issues to track public bugs. Report a bug by [opening a new issue]
 
 ## Use a Consistent Coding Style
 
-* Use [Black](https://github.com/psf/black) for Python code formatting
-* Keep line length to 88 characters (Black default)
+* Use `uv run ruff format .` for formatting
+* Use `uv run ruff check .` for linting and import ordering
+* Keep line length to 88 characters
 * Use type hints for function arguments and return values
 * Write docstrings for all public functions and classes
 
 ## Running Tests
 
 ```bash
-pytest tests/
+uv run python -m pytest tests/ -q
 ```
 
 ## License

pyarallel-0.6.0/Makefile

@@ -0,0 +1,45 @@
+.PHONY: help test docs-serve docs-deploy format lint clean build publish
+
+help:
+	@echo "Available commands:"
+	@echo "  make test         Run pytest suite"
+	@echo "  make docs-serve   Start mkdocs development server"
+	@echo "  make docs-deploy  Deploy documentation to GitHub Pages"
+	@echo "  make format      Format code with ruff"
+	@echo "  make lint        Run ruff check + mypy"
+	@echo "  make clean       Remove build artifacts"
+	@echo "  make build       Build package"
+	@echo "  make publish     Publish package to PyPI"
+
+test:
+	uv run pytest tests/ -v
+
+docs-serve:
+	uv run mkdocs serve
+
+docs-deploy:
+	uv run mkdocs gh-deploy
+
+format:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+lint:
+	uv run ruff check .
+	uv run mypy pyarallel/ tests/typing_assertions.py
+
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name '*.pyc' -delete
+	find . -type f -name '*.pyo' -delete
+	find . -type f -name '*.pyd' -delete
+
+build:
+	$(MAKE) clean
+	uv run python -m build
+
+publish: build
+	uv run twine upload dist/*

pyarallel-0.6.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: pyarallel
+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
+Author-email: Mehmet Oner Yalcin <oneryalcin@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Pyarallel Contributors
+        
+        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.
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Pyarallel
+
+[![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)
+
+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 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+.**
+
+## Before / After
+
+Fetch 10,000 URLs with rate limiting and error handling.
+
+**concurrent.futures:**
+
+```python
+import requests
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+def fetch(url):
+    return requests.get(url, timeout=10).json()
+
+urls = ["https://api.example.com/users/1", "https://api.example.com/users/2", ...]
+
+results = [None] * len(urls)
+errors = []
+
+with ThreadPoolExecutor(max_workers=10) as pool:
+    futures = {pool.submit(fetch, url): i for i, url in enumerate(urls)}
+    for f in as_completed(futures):
+        i = futures[f]
+        try:
+            results[i] = f.result()
+        except Exception as e:
+            errors.append((i, e))
+
+# No rate limiting. No retry. No resume. And you still
+# need to wire those yourself every time.
+```
+
+**pyarallel:**
+
+```python
+from pyarallel import parallel_map, RateLimit, Retry
+
+result = parallel_map(
+    fetch, urls,
+    workers=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, on=(ConnectionError, TimeoutError)),
+)
+
+for idx, val in result.successes():
+    save(val)
+for idx, exc in result.failures():
+    log_error(idx, exc)
+```
+
+Same thing, async:
+
+```python
+import httpx
+from pyarallel import async_parallel_map, RateLimit, Retry
+
+async def fetch_async(url):
+    async with httpx.AsyncClient() as client:
+        return (await client.get(url, timeout=10)).json()
+
+result = await async_parallel_map(
+    fetch_async, urls,
+    concurrency=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, on=(ConnectionError, TimeoutError)),
+)
+# Same result model — result.ok, result.successes(), result.failures()
+```
+
+## Install
+
+```bash
+pip install pyarallel
+```
+
+## What You Get
+
+- **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,))`
+- **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
+
+### Sync
+
+```python
+import requests
+from pyarallel import parallel_map, RateLimit, Retry
+
+def fetch(url):
+    return requests.get(url, timeout=10).json()
+
+# Fan out over a list, get ordered results
+result = parallel_map(fetch, urls, workers=10)
+
+# Rate-limited API calls with retry
+def call_api(user_id):
+    return requests.get(f"https://api.example.com/users/{user_id}").json()
+
+result = parallel_map(
+    call_api, user_ids,
+    workers=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, backoff=1.0, on=(ConnectionError, TimeoutError)),
+)
+
+# CPU-bound with processes
+from PIL import Image
+
+def resize_image(path):
+    img = Image.open(path)
+    img.thumbnail((800, 600))
+    img.save(path.replace(".png", "_thumb.png"))
+
+result = parallel_map(resize_image, paths, executor="process")
+```
+
+### Async
+
+```python
+import httpx
+from pyarallel import async_parallel_map
+
+async def fetch_async(url):
+    async with httpx.AsyncClient() as client:
+        return (await client.get(url, timeout=10)).json()
+
+result = await async_parallel_map(
+    fetch_async, urls, concurrency=20, task_timeout=5.0,
+)
+```
+
+### Decorator
+
+Adds `.map()`, `.starmap()`, `.stream()` without changing the function:
+
+```python
+from pyarallel import parallel, async_parallel, RateLimit
+
+@parallel(workers=8, rate_limit=RateLimit(100, "minute"))
+def fetch(url):
+    return requests.get(url).json()
+
+fetch("http://example.com")          # normal call — returns dict
+fetch.map(urls)                      # parallel — returns ParallelResult
+fetch.stream(urls, batch_size=500)   # streaming — yields ItemResult
+
+@async_parallel(concurrency=10)
+async def fetch_async(url):
+    async with httpx.AsyncClient() as c:
+        return (await c.get(url)).json()
+
+await fetch_async.map(urls)          # async parallel
+```
+
+### Streaming — Constant Memory
+
+For ETL, pipelines, or datasets too large to hold in memory:
+
+```python
+from pyarallel import parallel_iter
+
+def transform(row):
+    return {"id": row["id"], "name": row["name"].strip().title()}
+
+for item in parallel_iter(transform, ten_million_rows, batch_size=1000):
+    if item.ok:
+        db.save(item.value)
+    else:
+        log_error(item.index, item.error)
+```
+
+### Error Handling
+
+All errors collected, never silently swallowed:
+
+```python
+def send_email(msg):
+    return smtp.send(msg["to"], msg["subject"], msg["body"])
+
+result = parallel_map(send_email, messages)
+
+if result.ok:
+    values = result.values()           # list of all results, in order
+else:
+    for idx, exc in result.failures():
+        log_error(idx, exc)
+    result.raise_on_failure()          # or raise ExceptionGroup with all errors
+```
+
+## API Summary
+
+| Function | Decorator | Returns | Use case |
+|---|---|---|---|
+| `parallel_map(fn, items)` | `.map(items)` | `ParallelResult` | Results fit in memory |
+| `parallel_starmap(fn, items)` | `.starmap(items)` | `ParallelResult` | Multi-arg, fits in memory |
+| `parallel_iter(fn, items)` | `.stream(items)` | `Iterator[ItemResult]` | Streaming, constant memory |
+
+Async mirrors: `async_parallel_map`, `async_parallel_starmap`, `async_parallel_iter`
+
+| Config | Example |
+|---|---|
+| `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/).
+
+## Documentation
+
+[Full docs](https://oneryalcin.github.io/pyarallel/) — API reference, advanced features, best practices.
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

pyarallel-0.6.0/README.md

@@ -0,0 +1,237 @@
+# Pyarallel
+
+[![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)
+
+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 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+.**
+
+## Before / After
+
+Fetch 10,000 URLs with rate limiting and error handling.
+
+**concurrent.futures:**
+
+```python
+import requests
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+def fetch(url):
+    return requests.get(url, timeout=10).json()
+
+urls = ["https://api.example.com/users/1", "https://api.example.com/users/2", ...]
+
+results = [None] * len(urls)
+errors = []
+
+with ThreadPoolExecutor(max_workers=10) as pool:
+    futures = {pool.submit(fetch, url): i for i, url in enumerate(urls)}
+    for f in as_completed(futures):
+        i = futures[f]
+        try:
+            results[i] = f.result()
+        except Exception as e:
+            errors.append((i, e))
+
+# No rate limiting. No retry. No resume. And you still
+# need to wire those yourself every time.
+```
+
+**pyarallel:**
+
+```python
+from pyarallel import parallel_map, RateLimit, Retry
+
+result = parallel_map(
+    fetch, urls,
+    workers=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, on=(ConnectionError, TimeoutError)),
+)
+
+for idx, val in result.successes():
+    save(val)
+for idx, exc in result.failures():
+    log_error(idx, exc)
+```
+
+Same thing, async:
+
+```python
+import httpx
+from pyarallel import async_parallel_map, RateLimit, Retry
+
+async def fetch_async(url):
+    async with httpx.AsyncClient() as client:
+        return (await client.get(url, timeout=10)).json()
+
+result = await async_parallel_map(
+    fetch_async, urls,
+    concurrency=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, on=(ConnectionError, TimeoutError)),
+)
+# Same result model — result.ok, result.successes(), result.failures()
+```
+
+## Install
+
+```bash
+pip install pyarallel
+```
+
+## What You Get
+
+- **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,))`
+- **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
+
+### Sync
+
+```python
+import requests
+from pyarallel import parallel_map, RateLimit, Retry
+
+def fetch(url):
+    return requests.get(url, timeout=10).json()
+
+# Fan out over a list, get ordered results
+result = parallel_map(fetch, urls, workers=10)
+
+# Rate-limited API calls with retry
+def call_api(user_id):
+    return requests.get(f"https://api.example.com/users/{user_id}").json()
+
+result = parallel_map(
+    call_api, user_ids,
+    workers=10,
+    rate_limit=RateLimit(100, "minute"),
+    retry=Retry(attempts=3, backoff=1.0, on=(ConnectionError, TimeoutError)),
+)
+
+# CPU-bound with processes
+from PIL import Image
+
+def resize_image(path):
+    img = Image.open(path)
+    img.thumbnail((800, 600))
+    img.save(path.replace(".png", "_thumb.png"))
+
+result = parallel_map(resize_image, paths, executor="process")
+```
+
+### Async
+
+```python
+import httpx
+from pyarallel import async_parallel_map
+
+async def fetch_async(url):
+    async with httpx.AsyncClient() as client:
+        return (await client.get(url, timeout=10)).json()
+
+result = await async_parallel_map(
+    fetch_async, urls, concurrency=20, task_timeout=5.0,
+)
+```
+
+### Decorator
+
+Adds `.map()`, `.starmap()`, `.stream()` without changing the function:
+
+```python
+from pyarallel import parallel, async_parallel, RateLimit
+
+@parallel(workers=8, rate_limit=RateLimit(100, "minute"))
+def fetch(url):
+    return requests.get(url).json()
+
+fetch("http://example.com")          # normal call — returns dict
+fetch.map(urls)                      # parallel — returns ParallelResult
+fetch.stream(urls, batch_size=500)   # streaming — yields ItemResult
+
+@async_parallel(concurrency=10)
+async def fetch_async(url):
+    async with httpx.AsyncClient() as c:
+        return (await c.get(url)).json()
+
+await fetch_async.map(urls)          # async parallel
+```
+
+### Streaming — Constant Memory
+
+For ETL, pipelines, or datasets too large to hold in memory:
+
+```python
+from pyarallel import parallel_iter
+
+def transform(row):
+    return {"id": row["id"], "name": row["name"].strip().title()}
+
+for item in parallel_iter(transform, ten_million_rows, batch_size=1000):
+    if item.ok:
+        db.save(item.value)
+    else:
+        log_error(item.index, item.error)
+```
+
+### Error Handling
+
+All errors collected, never silently swallowed:
+
+```python
+def send_email(msg):
+    return smtp.send(msg["to"], msg["subject"], msg["body"])
+
+result = parallel_map(send_email, messages)
+
+if result.ok:
+    values = result.values()           # list of all results, in order
+else:
+    for idx, exc in result.failures():
+        log_error(idx, exc)
+    result.raise_on_failure()          # or raise ExceptionGroup with all errors
+```
+
+## API Summary
+
+| Function | Decorator | Returns | Use case |
+|---|---|---|---|
+| `parallel_map(fn, items)` | `.map(items)` | `ParallelResult` | Results fit in memory |
+| `parallel_starmap(fn, items)` | `.starmap(items)` | `ParallelResult` | Multi-arg, fits in memory |
+| `parallel_iter(fn, items)` | `.stream(items)` | `Iterator[ItemResult]` | Streaming, constant memory |
+
+Async mirrors: `async_parallel_map`, `async_parallel_starmap`, `async_parallel_iter`
+
+| Config | Example |
+|---|---|
+| `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/).
+
+## Documentation
+
+[Full docs](https://oneryalcin.github.io/pyarallel/) — API reference, advanced features, best practices.
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).