haiway 0.24.0__py3-none-any.whl → 0.24.2__py3-none-any.whl

haiway/__init__.py

@@ -18,8 +18,10 @@ from haiway.helpers import (
     LoggerObservability,
     asynchronous,
     cache,
+    execute_concurrently,
     process_concurrently,
     retry,
+    stream_concurrently,
     throttle,
     timeout,
     traced,
@@ -90,6 +92,7 @@ __all__ = (
     "asynchronous",
     "cache",
     "ctx",
+    "execute_concurrently",
     "getenv",
     "getenv_base64",
     "getenv_bool",
@@ -103,6 +106,7 @@ __all__ = (
     "process_concurrently",
     "retry",
     "setup_logging",
+    "stream_concurrently",
     "throttle",
     "timeout",
     "traced",

haiway/helpers/__init__.py

@@ -1,6 +1,10 @@
 from haiway.helpers.asynchrony import asynchronous
 from haiway.helpers.caching import CacheMakeKey, CacheRead, CacheWrite, cache
-from haiway.helpers.concurrent import process_concurrently
+from haiway.helpers.concurrent import (
+    execute_concurrently,
+    process_concurrently,
+    stream_concurrently,
+)
 from haiway.helpers.files import File, FileAccess
 from haiway.helpers.observability import LoggerObservability
 from haiway.helpers.retries import retry
@@ -17,8 +21,10 @@ __all__ = (
     "LoggerObservability",
     "asynchronous",
     "cache",
+    "execute_concurrently",
     "process_concurrently",
     "retry",
+    "stream_concurrently",
     "throttle",
     "timeout",
     "traced",

haiway/helpers/concurrent.py

@@ -1,11 +1,22 @@
-from asyncio import FIRST_COMPLETED, CancelledError, Task, wait
-from collections.abc import AsyncIterator, Callable, Coroutine
-from concurrent.futures import ALL_COMPLETED
-from typing import Any
+from asyncio import ALL_COMPLETED, FIRST_COMPLETED, CancelledError, Task, wait
+from collections.abc import (
+    AsyncIterable,
+    AsyncIterator,
+    Callable,
+    Collection,
+    Coroutine,
+    MutableSequence,
+    Sequence,
+)
+from typing import Any, Literal, overload
 
 from haiway.context import ctx
 
-__all__ = ("process_concurrently",)
+__all__ = (
+    "execute_concurrently",
+    "process_concurrently",
+    "stream_concurrently",
+)
 
 
 async def process_concurrently[Element](  # noqa: C901, PLR0912
@@ -18,20 +29,52 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
 ) -> None:
     """Process elements from an async iterator concurrently.
 
+    Consumes elements from an async iterator and processes them using the provided
+    handler function. Processing happens concurrently with a configurable maximum
+    number of concurrent tasks. Elements are processed as they become available,
+    maintaining the specified concurrency limit.
+
+    The function continues until the source iterator is exhausted. If the function
+    is cancelled, all running tasks are also cancelled. When ignore_exceptions is
+    False, the first exception encountered will stop processing and propagate.
+
     Parameters
     ----------
-    source: AsyncIterator[Element]
-        An async iterator providing elements to process.
+    source : AsyncIterator[Element]
+        An async iterator providing elements to process. Elements are consumed
+        one at a time as processing slots become available.
+    handler : Callable[[Element], Coroutine[Any, Any, None]]
+        A coroutine function that processes each element. The handler should
+        not return a value (returns None).
+    concurrent_tasks : int, default=2
+        Maximum number of concurrent tasks. Must be greater than 0. Higher
+        values allow more parallelism but consume more resources.
+    ignore_exceptions : bool, default=False
+        If True, exceptions from handler tasks will be logged but not propagated,
+        allowing processing to continue. If False, the first exception stops
+        all processing.
 
-    handler: Callable[[Element], Coroutine[Any, Any, None]]
-        A coroutine function that processes each element.
+    Raises
+    ------
+    CancelledError
+        If the function is cancelled, propagated after cancelling all running tasks.
+    Exception
+        Any exception raised by handler tasks when ignore_exceptions is False.
 
-    concurrent_tasks: int
-        Maximum number of concurrent tasks (must be > 0), default is 2.
-
-    ignore_exceptions: bool
-        If True, exceptions from tasks will be logged but not propagated,
-         default is False.
+    Examples
+    --------
+    >>> async def process_item(item: str) -> None:
+    ...     await some_async_operation(item)
+    ...
+    >>> async def items() -> AsyncIterator[str]:
+    ...     for i in range(10):
+    ...         yield f"item_{i}"
+    ...
+    >>> await process_concurrently(
+    ...     items(),
+    ...     process_item,
+    ...     concurrent_tasks=5
+    ... )
 
     """
     assert concurrent_tasks > 0  # nosec: B101
@@ -83,3 +126,269 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
                         f"Concurrent processing error - {type(exc)}: {exc}",
                         exception=exc,
                     )
+
+
+@overload
+async def execute_concurrently[Element, Result](
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+) -> Sequence[Result]: ...
+
+
+@overload
+async def execute_concurrently[Element, Result](
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+    return_exceptions: Literal[True],
+) -> Sequence[Result | BaseException]: ...
+
+
+async def execute_concurrently[Element, Result](  # noqa: C901
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+    return_exceptions: bool = False,
+) -> Sequence[Result | BaseException] | Sequence[Result]:
+    """Execute handler for each element from a collection concurrently.
+
+    Processes all elements from a collection using the provided handler function,
+    executing multiple handlers concurrently up to the specified limit. Results
+    are collected and returned in the same order as the input elements.
+
+    Unlike `process_concurrently`, this function:
+    - Works with collections (known size) rather than async iterators
+    - Returns results from each handler invocation
+    - Preserves the order of results to match input order
+
+    The function ensures all tasks complete before returning. If cancelled,
+    all running tasks are cancelled before propagating the cancellation.
+
+    Parameters
+    ----------
+    source : Collection[Element]
+        A collection of elements to process. The collection size determines
+        the result sequence length.
+    handler : Callable[[Element], Coroutine[Any, Any, Result]]
+        A coroutine function that processes each element and returns a result.
+    concurrent_tasks : int, default=2
+        Maximum number of concurrent tasks. Must be greater than 0. Higher
+        values allow more parallelism but consume more resources.
+    return_exceptions : bool, default=False
+        If True, exceptions from handler tasks are included in the results
+        as BaseException instances. If False, the first exception stops
+        processing and is raised.
+
+    Returns
+    -------
+    Sequence[Result] or Sequence[Result | BaseException]
+        Results from each handler invocation, in the same order as input elements.
+        If return_exceptions is True, failed tasks return BaseException instances.
+
+    Raises
+    ------
+    CancelledError
+        If the function is cancelled, propagated after cancelling all running tasks.
+    Exception
+        Any exception raised by handler tasks when return_exceptions is False.
+
+    Examples
+    --------
+    >>> async def fetch_data(url: str) -> dict:
+    ...     return await http_client.get(url)
+    ...
+    >>> urls = ["http://api.example.com/1", "http://api.example.com/2"]
+    >>> results = await execute_concurrently(
+    ...     urls,
+    ...     fetch_data,
+    ...     concurrent_tasks=10
+    ... )
+    >>> # results[0] corresponds to urls[0], results[1] to urls[1], etc.
+
+    >>> # With exception handling
+    >>> results = await execute_concurrently(
+    ...     urls,
+    ...     fetch_data,
+    ...     concurrent_tasks=10,
+    ...     return_exceptions=True
+    ... )
+    >>> for url, result in zip(urls, results):
+    ...     if isinstance(result, BaseException):
+    ...         print(f"Failed to fetch {url}: {result}")
+    ...     else:
+    ...         print(f"Got data from {url}")
+
+    """
+    assert concurrent_tasks > 0  # nosec: B101
+    running: set[Task[Result]] = set()
+    results: MutableSequence[Task[Result]] = []
+    try:
+        for element in source:
+            task: Task[Result] = ctx.spawn(handler, element)
+            results.append(task)
+            running.add(task)
+            if len(running) < concurrent_tasks:
+                continue  # keep spawning tasks
+
+            completed, running = await wait(
+                running,
+                return_when=FIRST_COMPLETED,
+            )
+
+            for task in completed:
+                if exc := task.exception():
+                    if not return_exceptions:
+                        raise exc
+
+                    ctx.log_error(
+                        f"Concurrent execution error - {type(exc)}: {exc}",
+                        exception=exc,
+                    )
+
+    except CancelledError as exc:
+        # Cancel all running tasks
+        for task in running:
+            task.cancel()
+
+        raise exc
+
+    finally:
+        if running:
+            completed, _ = await wait(
+                running,
+                return_when=ALL_COMPLETED,
+            )
+            for task in completed:
+                if exc := task.exception():
+                    if not return_exceptions:
+                        raise exc
+
+                    ctx.log_error(
+                        f"Concurrent execution error - {type(exc)}: {exc}",
+                        exception=exc,
+                    )
+
+    return [result.exception() or result.result() for result in results]
+
+
+async def stream_concurrently[ElementA, ElementB](  # noqa: C901
+    source_a: AsyncIterator[ElementA],
+    source_b: AsyncIterator[ElementB],
+    /,
+) -> AsyncIterable[ElementA | ElementB]:
+    """Merge streams from two async iterators processed concurrently.
+
+    Concurrently consumes elements from two async iterators and yields them
+    as they become available. Elements from both sources are interleaved based
+    on which iterator produces them first. The function continues until both
+    iterators are exhausted.
+
+    This is useful for combining multiple async data sources into a single
+    stream while maintaining concurrency. Each iterator is polled independently,
+    and whichever has data available first will have its element yielded.
+
+    Parameters
+    ----------
+    source_a : AsyncIterator[ElementA]
+        First async iterator to consume from.
+    source_b : AsyncIterator[ElementB]
+        Second async iterator to consume from.
+
+    Yields
+    ------
+    ElementA | ElementB
+        Elements from either source as they become available. The order
+        depends on which iterator produces elements first.
+
+    Raises
+    ------
+    CancelledError
+        If the async generator is cancelled, both source tasks are cancelled
+        before propagating the cancellation.
+    Exception
+        Any exception raised by either source iterator.
+
+    Examples
+    --------
+    >>> async def numbers() -> AsyncIterator[int]:
+    ...     for i in range(5):
+    ...         await asyncio.sleep(0.1)
+    ...         yield i
+    ...
+    >>> async def letters() -> AsyncIterator[str]:
+    ...     for c in "abcde":
+    ...         await asyncio.sleep(0.15)
+    ...         yield c
+    ...
+    >>> async for item in stream_concurrently(numbers(), letters()):
+    ...     print(item)  # Prints interleaved numbers and letters
+
+    Notes
+    -----
+    The function maintains exactly one pending task per iterator at all times,
+    ensuring efficient resource usage while maximizing throughput from both
+    sources.
+
+    """
+
+    async def next_a() -> ElementA:
+        return await anext(source_a)
+
+    async def next_b() -> ElementB:
+        return await anext(source_b)
+
+    task_a: Task[ElementA] = ctx.spawn(next_a)
+    task_b: Task[ElementB] = ctx.spawn(next_b)
+
+    try:
+        while not (  # Continue until both iterators are exhausted
+            task_a.done()
+            and task_b.done()
+            and isinstance(task_a.exception(), StopAsyncIteration)
+            and isinstance(task_b.exception(), StopAsyncIteration)
+        ):
+            # Wait for at least one task to complete
+            done, _ = await wait(
+                {task_a, task_b},
+                return_when=FIRST_COMPLETED,
+            )
+
+            # Process completed tasks
+            for task in done:
+                if task is task_a:
+                    exc: BaseException | None = task.exception()
+                    if exc is None:
+                        yield task.result()
+                        task_a = ctx.spawn(next_a)
+
+                    elif not isinstance(exc, StopAsyncIteration):
+                        raise exc
+                    # If StopAsyncIteration, don't respawn task_a
+
+                elif task is task_b:
+                    exc: BaseException | None = task.exception()
+                    if exc is None:
+                        yield task.result()
+                        task_b = ctx.spawn(next_b)
+
+                    elif not isinstance(exc, StopAsyncIteration):
+                        raise exc
+                    # If StopAsyncIteration, don't respawn task_b
+
+    except CancelledError as exc:
+        # Cancel all running tasks
+        task_a.cancel()
+        task_b.cancel()
+        raise exc
+
+    finally:
+        # Ensure cleanup of any remaining tasks
+        for task in (task_a, task_b):
+            task.cancel()

{haiway-0.24.0.dist-info → haiway-0.24.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.24.0
+Version: 0.24.2
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git

{haiway-0.24.0.dist-info → haiway-0.24.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-haiway/__init__.py,sha256=ONQA_EnbH6QjWLi-tOUeq6e6Wz8RL5lUd02qOURvz2A,1947
+haiway/__init__.py,sha256=5-zrkIqG6vMupL_Oh_KPqGXaEqAVj1FSed4BK_x0Nv0,2053
 haiway/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 haiway/context/__init__.py,sha256=1N_SvdPkTfIZDZybm3y0rY2dGrDLWTm0ryzUz2XD4f8,1174
 haiway/context/access.py,sha256=lsK6RnSjaGRgdOprtLCz4vyw5KqMtbGs0uFXnJWc_j4,24446
@@ -8,10 +8,10 @@ haiway/context/observability.py,sha256=JGiBScElJMgYDxi1PoIx7K98PpCXTVV3WY-x8abLx
 haiway/context/state.py,sha256=lzkVVdTMYn-Bfon2aCPMx6vRScrbOqY2f_DuS5aMx0s,11982
 haiway/context/tasks.py,sha256=pScFgeiyrXSJRDFZiYbBLi3k_DHkSlhB8rgAnYtgyrU,4925
 haiway/context/types.py,sha256=LoW8238TTdbUgmxyHDi0LVc8M8ZwTHLWKkAPttTsTeg,746
-haiway/helpers/__init__.py,sha256=PTWpavAveEB2V9Au1QuaRZwh3Rkb1bQSNvo_mxuGqlE,721
+haiway/helpers/__init__.py,sha256=J1WQdI2jD_zDP4azn9Me6hVvaBtz8kh9kTN-jDgDA5U,836
 haiway/helpers/asynchrony.py,sha256=Ddj8UdXhVczAbAC-rLpyhWa4RJ_W2Eolo45Veorq7_4,5362
 haiway/helpers/caching.py,sha256=BqgcUGQSAmXsuLi5V8EwlZzuGyutHOn1V4k7BHsGKeg,14347
-haiway/helpers/concurrent.py,sha256=xGMcan_tiETAHQs1YFmgYpA4YMFo6rIbFKvNeMlRFG8,2551
+haiway/helpers/concurrent.py,sha256=P8YXukabb29iQhSKTECVaThPhzTX17JDdKrWAjHy4d4,13105
 haiway/helpers/files.py,sha256=L6vXd8gdgWx5jPL8azloU8IGoFq2xnxjMc4ufz-gdl4,11650
 haiway/helpers/observability.py,sha256=jCJzOPJ5E3RKJsbbGRR1O-mZydaHNIGkIpppOH7nFBA,11012
 haiway/helpers/retries.py,sha256=OH__I9e-PUFxcSwuQLIzJ9F1MwXgbz1Ur4jEjJiOmjQ,8974
@@ -39,7 +39,7 @@ haiway/utils/mimic.py,sha256=xaZiUKp096QFfdSw7cNIKEWt2UIS7vf880KF54gny38,1831
 haiway/utils/noop.py,sha256=U8ocfoCgt-pY0owJDPtrRrj53cabeIXH9qCKWMQnoRk,1336
 haiway/utils/queue.py,sha256=6v2u3pA6A44IuCCTOjmCt3yLyOcm7PCRnrIGo25j-1o,6402
 haiway/utils/stream.py,sha256=lXaeveTY0-AYG5xVzcQYaiC6SUD5fUtHoMXiQcrQAAM,5723
-haiway-0.24.0.dist-info/METADATA,sha256=m5GgKDh6PnOTyN9WE222XuEUFE85MGhMPy1GXc8_A4g,4919
-haiway-0.24.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.24.0.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
-haiway-0.24.0.dist-info/RECORD,,
+haiway-0.24.2.dist-info/METADATA,sha256=nNfy1ktM-nzZnRYVfAz7QvTBQRZQqE_-NuUm5dz4NWs,4919
+haiway-0.24.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.24.2.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.24.2.dist-info/RECORD,,