ea-singleflight 0.1.0__py3-none-any.whl

ea_singleflight-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: ea-singleflight
+Version: 0.1.0
+Summary: An asynchronous request coalescing utility for Python.
+Author: Emil
+Author-email: Emil <emilupx@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/EmilAyupov/ea-singleflight
+Project-URL: Repository, https://github.com/EmilAyupov/ea-singleflight
+Project-URL: Issues, https://github.com/EmilAyupov/ea-singleflight/issues
+Description-Content-Type: text/markdown
+
+# SingleFlight
+
+**SingleFlight** is a lightweight asynchronous Python utility that prevents duplicate concurrent operations.
+
+When multiple callers request the same operation using the same key, only one operation is executed. All callers share the result of that operation.
+
+## Features
+
+- Deduplicates concurrent operations by key.
+- Shares results between multiple callers.
+- Propagates exceptions to all waiting callers.
+- Protects shared operations from individual caller cancellation.
+- Supports independent operations for different keys.
+- Automatically cleans up completed operations.
+- Built with Python's standard `asyncio` library.
+
+## Requirements
+
+- Python 3.13+
+
+## Installation
+
+The package is distributed as `ea-singleflight` and imported as `singleflight`.
+
+Once published on PyPI, install it with:
+
+```bash
+pip install ea-singleflight
+```
+
+Until then, you can install it directly from GitHub:
+
+```bash
+pip install git+https://github.com/EmilAyupov/ea-singleflight.git
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from singleflight import SingleFlight
+
+
+async def fetch_user(user_id: int) -> dict:
+    print(f"Fetching user {user_id}...")
+
+    await asyncio.sleep(1)
+
+    return {
+        "id": user_id,
+        "name": "Alice",
+    }
+
+
+async def main() -> None:
+    group = SingleFlight()
+
+    results = await asyncio.gather(
+        group.do("user:123", lambda: fetch_user(123)),
+        group.do("user:123", lambda: fetch_user(123)),
+        group.do("user:123", lambda: fetch_user(123)),
+    )
+
+    print(results)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Although three callers request the same operation, `fetch_user()` is executed only once.
+
+All three callers receive the same result.
+
+## How It Works
+
+SingleFlight maintains a collection of in-flight operations indexed by string keys.
+
+When `do()` is called:
+
+1. If no operation exists for the given key, a new asynchronous task is created.
+2. If an operation already exists, the caller joins the existing task.
+3. All callers await the same task.
+4. Once the operation completes and all waiting callers finish, the corresponding entry is removed.
+
+Operations with different keys run independently.
+
+## Cancellation Behavior
+
+SingleFlight uses `asyncio.shield()` to protect shared tasks from cancellation initiated by individual callers.
+
+If one caller is cancelled:
+
+- That caller receives `asyncio.CancelledError`.
+- The shared operation continues running.
+- Other callers can still receive its result.
+
+If all callers are cancelled, the shared operation continues running and can be joined by a new caller using the same key.
+
+## Exception Handling
+
+If the shared operation raises an exception, all waiting callers receive that exception.
+
+Once the operation has completed and its callers have finished, the corresponding entry is removed.
+
+A subsequent call using the same key starts a new operation.
+
+## API
+
+### `SingleFlight()`
+
+Creates a new SingleFlight instance.
+
+```python
+group = SingleFlight()
+```
+
+### `await group.do(key, fn)`
+
+Executes or joins an asynchronous operation associated with the given key.
+
+**Parameters:**
+
+| Parameter | Type       | Description                                  |
+| --------- | ---------- | -------------------------------------------- |
+| `key`     | `str`      | Identifier of the operation                  |
+| `fn`      | `Callable` | Zero-argument function returning a coroutine |
+
+**Returns:**
+
+The result of the shared asynchronous operation.
+
+**Raises:**
+
+- `TypeError` if `fn` does not return a coroutine.
+- Any exception raised by the shared operation.
+- `asyncio.CancelledError` if the individual caller is cancelled or the shared task is cancelled.
+
+## Limitations
+
+- Keys must be strings.
+- Only asynchronous functions returning coroutines are supported.
+- Callers using the same key must expect compatible results.
+- The first caller's function is used; subsequent functions for the same key are not executed.
+- A SingleFlight instance is intended for use within a single asyncio event loop.
+- The implementation is not thread-safe.
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/EmilAyupov/ea-singleflight.git
+cd ea-singleflight
+```
+
+Install dependencies:
+
+```bash
+uv sync --all-groups
+```
+
+Run checks:
+
+```bash
+./scripts/check.sh
+```
+
+The project uses:
+
+- [Python](https://www.python.org/)
+- [asyncio](https://docs.python.org/3/library/asyncio.html)
+- [pytest](https://pytest.org/)
+- [pytest-asyncio](https://pytest-asyncio.readthedocs.io/)
+- [Ruff](https://docs.astral.sh/ruff/)
+- [Pyrefly](https://pyrefly.org/)
+- [uv](https://docs.astral.sh/uv/)
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ea_singleflight-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+singleflight/__init__.py,sha256=3tG3dW1Cy6fHIcIdhhUHA65xUQMdNIOeweV5YFlx3_k,59
+singleflight/main.py,sha256=mlW1lZqWkso97gZ493A0D-XrX55o1zyfbnYbFNe7FOw,1601
+singleflight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ea_singleflight-0.1.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+ea_singleflight-0.1.0.dist-info/METADATA,sha256=3zFs6rfcuh1sfFDOpOExrBWpFZdTjotrovM3xNSKsJ8,5424
+ea_singleflight-0.1.0.dist-info/RECORD,,

ea_singleflight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

singleflight/__init__.py

@@ -0,0 +1,3 @@
+from .main import SingleFlight
+
+__all__ = ["SingleFlight"]

singleflight/main.py

@@ -0,0 +1,61 @@
+import asyncio
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+from typing import Any, TypeVar, cast
+
+T = TypeVar("T")
+
+
+@dataclass
+class Flight[T]:
+    task: asyncio.Task[T]
+    waiters: int = 0
+
+
+class SingleFlight:
+    def __init__(self) -> None:
+        self._flights: dict[str, Flight[Any]] = {}
+        self._lock = asyncio.Lock()
+
+    async def do(
+        self,
+        key: str,
+        fn: Callable[[], Coroutine[Any, Any, T]],
+    ) -> T:
+        async with self._lock:
+            flight = self._flights.get(key)
+
+            if flight is None:
+                coro = fn()
+
+                if not asyncio.iscoroutine(coro):
+                    raise TypeError("fn must return a coroutine")
+
+                task = asyncio.create_task(coro)
+                flight = Flight(task=task)
+                self._flights[key] = flight
+
+                task.add_done_callback(lambda _: self._on_task_done(key, flight))
+
+            flight.waiters += 1
+
+        try:
+            result = await asyncio.shield(flight.task)
+            return cast(T, result)
+        finally:
+            flight.waiters -= 1
+            self._cleanup(key, flight)
+
+    def _cleanup(self, key: str, flight: Flight[Any]) -> None:
+        if (
+            self._flights.get(key) is flight
+            and flight.task.done()
+            and flight.waiters == 0
+        ):
+            del self._flights[key]
+
+    def _on_task_done(self, key: str, flight: Flight[Any]) -> None:
+        if not flight.task.cancelled():
+            flight.task.exception()
+
+        self._cleanup(key, flight)