concresce 0.1.0__tar.gz

concresce-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: concresce
+Version: 0.1.0
+Summary: Transparent temporal coalescing and inline micro-batching for Python.
+Keywords: asyncio,batching,micro-batch,performance,coalesce
+Author: Wannes Vantorre
+Author-email: Wannes Vantorre <vantorrewannes@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.14
+Project-URL: Homepage, https://codeberg.org/ProductionCode/concresce
+Project-URL: Repository, https://codeberg.org/ProductionCode/concresce.git
+Project-URL: Issues, https://codeberg.org/ProductionCode/concresce/issues
+Description-Content-Type: text/markdown
+
+# concresce 💧
+
+**Transparent temporal coalescing and inline micro-batching.**
+
+Standard solutions to N+1 database or network bottlenecks require spinning up external message queues, background workers, or complex task graphs. `concresce` solves this dynamically. You write the function as if it processes a single item, and the runtime transparently merges concurrent calls into a single batch in the background.
+
+```bash
+uv add concresce
+```
+
+## The Difference
+
+| Concept                    | Standard Async Loop     | Message Queues (Celery/Kafka)    | `concresce`                         |
+| :------------------------- | :---------------------- | :------------------------------- | :---------------------------------- |
+| **Network Footprint**      | N requests for N items. | 1 request for N items.           | 1 request for N items.              |
+| **Architectural Overhead** | None.                   | High (Requires external broker). | None (Pure inline code).            |
+| **Return Routing**         | Native variables.       | Complex (Webhooks / Polling).    | Native variables (Futures resolve). |
+
+## Usage
+
+You need exactly three primitives: `@batch` to define the barrier constraints, `collect()` to suspend the execution and pool data, and `scatter()` to distribute the results back to the original callers.
+
+```python
+import asyncio
+from concresce import batch, collect, scatter
+
+@batch(max_window=0.05, max_size=100)
+async def fetch_user_score(user_id):
+    # 1. Execution pauses here.
+    # Concurrent calls to this function pool their `user_id`s together.
+    batch_ids = await collect(user_id)
+
+    # 2. Only ONE execution path (the leader) resumes from this point.
+    # The others remain safely suspended in the event loop.
+    print(f"Making 1 network call for {len(batch_ids)} users...")
+    bulk_results = await db.bulk_fetch_scores(batch_ids)
+
+    # 3. The leader distributes the results back to the suspended followers.
+    # Every caller gets their specific integer back.
+    return scatter(bulk_results)
+
+
+async def main():
+    # Fire off 5 requests simultaneously
+    results = await asyncio.gather(
+        fetch_user_score(1),
+        fetch_user_score(2),
+        fetch_user_score(3),
+        fetch_user_score(4),
+        fetch_user_score(5)
+    )
+
+    # Returns: [100, 250, 190, 300, 120]
+    print(results)
+
+asyncio.run(main())
+```
+
+## Core Mechanics
+
+- **Dual-Trigger Barrier:** The suspension breaks when either `max_size` is reached (volumetric) or `max_window` expires (temporal). High throughput processes instantly; low throughput falls back to the maximum allowed latency.
+- **Keyed Routing:** If your bulk API returns data out-of-order or drops missing items, you can pass a dictionary to `scatter({id: result})`. It will automatically route the correct result back to the specific caller based on their original input.
+- **Fault Propagation:** If the leader crashes during the heavy processing phase, the exception is safely replicated to all suspended followers. Nobody hangs, and the stack unwinds naturally.
+- **Contextual Safety:** If the leader attempts to return without calling `scatter()`, `concresce` detects the structural failure and safely aborts the followers with a `RuntimeError` rather than leaving them deadlocked.

concresce-0.1.0/README.md

@@ -0,0 +1,64 @@
+# concresce 💧
+
+**Transparent temporal coalescing and inline micro-batching.**
+
+Standard solutions to N+1 database or network bottlenecks require spinning up external message queues, background workers, or complex task graphs. `concresce` solves this dynamically. You write the function as if it processes a single item, and the runtime transparently merges concurrent calls into a single batch in the background.
+
+```bash
+uv add concresce
+```
+
+## The Difference
+
+| Concept                    | Standard Async Loop     | Message Queues (Celery/Kafka)    | `concresce`                         |
+| :------------------------- | :---------------------- | :------------------------------- | :---------------------------------- |
+| **Network Footprint**      | N requests for N items. | 1 request for N items.           | 1 request for N items.              |
+| **Architectural Overhead** | None.                   | High (Requires external broker). | None (Pure inline code).            |
+| **Return Routing**         | Native variables.       | Complex (Webhooks / Polling).    | Native variables (Futures resolve). |
+
+## Usage
+
+You need exactly three primitives: `@batch` to define the barrier constraints, `collect()` to suspend the execution and pool data, and `scatter()` to distribute the results back to the original callers.
+
+```python
+import asyncio
+from concresce import batch, collect, scatter
+
+@batch(max_window=0.05, max_size=100)
+async def fetch_user_score(user_id):
+    # 1. Execution pauses here.
+    # Concurrent calls to this function pool their `user_id`s together.
+    batch_ids = await collect(user_id)
+
+    # 2. Only ONE execution path (the leader) resumes from this point.
+    # The others remain safely suspended in the event loop.
+    print(f"Making 1 network call for {len(batch_ids)} users...")
+    bulk_results = await db.bulk_fetch_scores(batch_ids)
+
+    # 3. The leader distributes the results back to the suspended followers.
+    # Every caller gets their specific integer back.
+    return scatter(bulk_results)
+
+
+async def main():
+    # Fire off 5 requests simultaneously
+    results = await asyncio.gather(
+        fetch_user_score(1),
+        fetch_user_score(2),
+        fetch_user_score(3),
+        fetch_user_score(4),
+        fetch_user_score(5)
+    )
+
+    # Returns: [100, 250, 190, 300, 120]
+    print(results)
+
+asyncio.run(main())
+```
+
+## Core Mechanics
+
+- **Dual-Trigger Barrier:** The suspension breaks when either `max_size` is reached (volumetric) or `max_window` expires (temporal). High throughput processes instantly; low throughput falls back to the maximum allowed latency.
+- **Keyed Routing:** If your bulk API returns data out-of-order or drops missing items, you can pass a dictionary to `scatter({id: result})`. It will automatically route the correct result back to the specific caller based on their original input.
+- **Fault Propagation:** If the leader crashes during the heavy processing phase, the exception is safely replicated to all suspended followers. Nobody hangs, and the stack unwinds naturally.
+- **Contextual Safety:** If the leader attempts to return without calling `scatter()`, `concresce` detects the structural failure and safely aborts the followers with a `RuntimeError` rather than leaving them deadlocked.

concresce-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "concresce"
+version = "0.1.0"
+description = "Transparent temporal coalescing and inline micro-batching for Python."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Wannes Vantorre", email = "vantorrewannes@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+keywords = ["asyncio", "batching", "micro-batch", "performance", "coalesce"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO"
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/ProductionCode/concresce"
+Repository = "https://codeberg.org/ProductionCode/concresce.git"
+Issues = "https://codeberg.org/ProductionCode/concresce/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=1.3.0",
+]

concresce-0.1.0/src/concresce/__init__.py

@@ -0,0 +1,3 @@
+from concresce.lib import batch, collect, scatter
+
+__all__ = ["batch", "collect", "scatter"]

concresce-0.1.0/src/concresce/lib.py

@@ -0,0 +1,134 @@
+import asyncio
+import functools
+from contextvars import ContextVar
+from typing import Any, Callable, Dict, Iterable, List, Optional, Union
+
+
+class Suspension(Exception):
+    def __init__(self, future: asyncio.Future):
+        self.future = future
+
+
+class Batch:
+    __slots__ = ("items", "futures", "event", "scattered")
+
+    def __init__(self):
+        self.items: List[Any] = []
+        self.futures: List[asyncio.Future] = []
+        self.event = asyncio.Event()
+        self.scattered = False
+
+    def fail(self, exception: Exception) -> None:
+        self.scattered = True
+        for f in self.futures[1:]:
+            if not f.done():
+                f.set_exception(exception)
+
+
+class Coordinator:
+    __slots__ = ("max_window", "max_size", "batch")
+
+    def __init__(self, max_window: float, max_size: int):
+        self.max_window = max_window
+        self.max_size = max_size
+        self.batch: Optional[Batch] = None
+
+
+_coord: ContextVar[Coordinator] = ContextVar("concresce_coord")
+_batch: ContextVar[Batch] = ContextVar("concresce_batch")
+
+
+async def collect(item: Any) -> List[Any]:
+    try:
+        coord = _coord.get()
+    except LookupError:
+        raise RuntimeError("Out of concresce context. Missing @concresce.batch?")
+
+    b = coord.batch
+    if b is None or b.event.is_set():
+        b = Batch()
+        coord.batch = b
+
+    _batch.set(b)
+
+    b.items.append(item)
+    fut = asyncio.get_running_loop().create_future()
+    b.futures.append(fut)
+
+    size = len(b.items)
+
+    if size == 1:
+        if coord.max_size > 1:
+            try:
+                await asyncio.wait_for(b.event.wait(), timeout=coord.max_window)
+            except asyncio.TimeoutError:
+                pass
+        b.event.set()
+        return b.items
+
+    if size >= coord.max_size:
+        b.event.set()
+
+    raise Suspension(fut)
+
+
+def scatter(results: Union[Dict[Any, Any], Iterable[Any]]) -> Any:
+    try:
+        b = _batch.get()
+    except LookupError:
+        raise RuntimeError("Out of concresce context. Did you call collect()?")
+
+    b.scattered = True
+
+    if isinstance(results, dict):
+        for i in range(1, len(b.items)):
+            fut = b.futures[i]
+            if not fut.done():
+                try:
+                    fut.set_result(results.get(b.items[i]))
+                except Exception as e:
+                    fut.set_exception(e)
+        return results.get(b.items[0])
+
+    seq = list(results)
+    for i in range(1, len(b.futures)):
+        fut = b.futures[i]
+        if not fut.done():
+            try:
+                fut.set_result(seq[i])
+            except Exception as e:
+                fut.set_exception(e)
+    return seq[0]
+
+
+def batch(max_window: float = 0.05, max_size: int = 100):
+    coord = Coordinator(max_window, max_size)
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            token = _coord.set(coord)
+            try:
+                result = await func(*args, **kwargs)
+
+                b = _batch.get(None)
+                if b and not b.scattered:
+                    b.fail(RuntimeError("Leader completed without scattering."))
+
+                return result
+
+            except Suspension as halt:
+                return await halt.future
+
+            except Exception as e:
+                b = _batch.get(None)
+                if b and not b.scattered:
+                    b.fail(e)
+                raise
+
+            finally:
+                _coord.reset(token)
+
+        return wrapper
+
+    return decorator