asyncio-extensions 0.3.2__tar.gz → 0.4.0__tar.gz

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/.github/workflows/tests.yml

@@ -27,16 +27,17 @@ jobs:
           python-version: "3.13"
 
       - name: Setup Hatch
-        run: pipx  install --preinstall "virtualenv<21" hatch
+        run: pipx  install hatch
 
       - name: Run static analysis
-        run: hatch fmt --check
+        run: hatch check code
+
+      - name: Verify formatting
+        run: hatch check fmt
 
-      - name: Type checking with MyPy
-        run: hatch run mypy src/asyncio_extensions
 
-      - name: Type checking with Pyrefly
-        run: hatch run pyrefly check src/asyncio_extensions
+      - name: Run type checks
+        run: hatch check types
 
   tests:
     name: Run tests on ${{ matrix.python-version }}

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/commitizen-tools/commitizen
-    rev: v4.18.1
+    rev: v4.19.0
     hooks:
       - id: commitizen
       - id: commitizen-branch

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/CHANGELOG.md

@@ -8,6 +8,12 @@ This project adheres to both [Semantic Versioning](https://semver.org/spec/v2.0.
 
 ## [UNRELEASED]
 
+## [0.4.0] - 2026-09-30
+
+### Added
+
+- `for_each_concurrent` coroutine to apply an async callback to each item in a sync or async iterable with bounded concurrency.
+
 ## [0.3.2] - 2026-09-24
 
 ### Fixed
@@ -104,7 +110,8 @@ This project adheres to both [Semantic Versioning](https://semver.org/spec/v2.0.
 - `checkpoint` function to yield control to the event loop.
 - `sleep_forever` function.
 
-[unreleased]: https://github.com/hartungstenio/asyncio-extensions/compare/0.3.2...HEAD
+[unreleased]: https://github.com/hartungstenio/asyncio-extensions/compare/0.4.0...HEAD
+[0.4.0]: https://github.com/hartungstenio/asyncio-extensions/compare/0.3.2...0.4.0
 [0.3.2]: https://github.com/hartungstenio/asyncio-extensions/compare/0.3.1...0.3.2
 [0.3.1]: https://github.com/hartungstenio/asyncio-extensions/compare/0.3.0...0.3.1
 [0.3.0]: https://github.com/hartungstenio/asyncio-extensions/compare/0.2.0...0.3.0

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: asyncio-extensions
-Version: 0.3.2
+Version: 0.4.0
 Summary: Some (maybe) useful extensions for asyncio
 Project-URL: Changelog, https://github.com/hartungstenio/asyncio-extensions/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/hartungstenio/asyncio-extensions#readme
@@ -406,6 +406,20 @@ async with aclosing(flatten_stream(merge_iterables(source_a, source_b))) as stre
             break
 ```
 
+### for_each_concurrent
+
+The `for_each_concurrent` coroutine applies an async callback to each item in a sync or async iterable, keeping at most `concurrency` calls running at the same time. Items are consumed in order, but callbacks may complete out of order.
+
+```python
+from asyncio_extensions import for_each_concurrent
+
+async def fetch(url: str) -> None:
+    response = await client.get(url)
+    await save(response)
+
+await for_each_concurrent(urls, fetch, concurrency=10)
+```
+
 ### iscoroutinefunction, markcoroutinefunction, and is_awaitable
 
 The `iscoroutinefunction` helper checks whether a callable is already a coroutine function. It is re-exported from `inspect` on newer Python versions and from `asyncio` on older versions, depending on the runtime.

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/README.md

@@ -376,6 +376,20 @@ async with aclosing(flatten_stream(merge_iterables(source_a, source_b))) as stre
             break
 ```
 
+### for_each_concurrent
+
+The `for_each_concurrent` coroutine applies an async callback to each item in a sync or async iterable, keeping at most `concurrency` calls running at the same time. Items are consumed in order, but callbacks may complete out of order.
+
+```python
+from asyncio_extensions import for_each_concurrent
+
+async def fetch(url: str) -> None:
+    response = await client.get(url)
+    await save(response)
+
+await for_each_concurrent(urls, fetch, concurrency=10)
+```
+
 ### iscoroutinefunction, markcoroutinefunction, and is_awaitable
 
 The `iscoroutinefunction` helper checks whether a callable is already a coroutine function. It is re-exported from `inspect` on newer Python versions and from `asyncio` on older versions, depending on the runtime.

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/pyproject.toml

@@ -39,12 +39,15 @@ Source = "https://github.com/hartungstenio/asyncio-extensions"
 [dependency-groups]
 dev = [
   "faker",
-  "mypy",
   "pre-commit",
-  "pyrefly",
   "pytest",
   "pytest-asyncio",
   "pytest-cov",
+  { include-group = "types" },
+]
+types = [
+  "mypy (>= 2.3)",
+  "pyrefly (>= 1.3)",
 ]
 
 [build-system]
@@ -71,6 +74,9 @@ exclude_also = [
   '@(typing\.)?overload',
 ]
 
+[tool.hatch]
+requires-hatch = ">= 1.18"
+
 [tool.hatch.version]
 source = "vcs"
 
@@ -78,9 +84,19 @@ source = "vcs"
 python = "3.13"
 dependency-groups = ["dev"]
 
+[tool.hatch.envs.hatch-check-types]
+dependencies = []
+dependency-groups = ["types"]
+
+[tool.hatch.envs.hatch-check-types.scripts]
+check = [
+  "pyrefly check{env:HATCH_CHECK_TYPES_ARGS:} {args}",
+  "mypy {args}",
+]
+
 [tool.hatch.envs.hatch-static-analysis]
 config-path = "none"
-dependencies = ["ruff (==0.15.*)"]
+dependencies = ["ruff (>= 0.16)"]
 
 [tool.hatch.envs.hatch-test]
 extra-dependencies = [
@@ -99,9 +115,11 @@ cov-report = "coverage xml"
 
 [tool.mypy]
 strict = true
+files = ["src"]
 enable_error_code = ["deprecated"]
 
 [tool.pyrefly]
+project-includes = ["src"]
 preset = "strict"
 min-severity = "ignore"
 
@@ -163,6 +181,7 @@ select = [
   "UP",
   "W",
 ]
+ignore = ["SIM105"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*.py" = ["D", "S101"]

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/src/asyncio_extensions/__init__.py

@@ -3,10 +3,10 @@
 from ._compat import CreateTaskParams as CreateTaskParams
 from ._compat import iscoroutinefunction as iscoroutinefunction
 from ._iterators import STOP as STOP
-from ._iterators import ManagedStream as ManagedStream
 from ._iterators import drain as drain
 from ._iterators import fill_queue as fill_queue
 from ._iterators import flatten_stream as flatten_stream
+from ._iterators import for_each_concurrent as for_each_concurrent
 from ._iterators import iterate_queue as iterate_queue
 from ._iterators import merge_iterables as merge_iterables
 from ._iterators import merge_streams as merge_streams
@@ -23,3 +23,4 @@ from ._task_groups import LimitedTaskGroup as LimitedTaskGroup
 from ._task_groups import TaskGroup as TaskGroup
 from ._task_groups import TerminateTaskGroup as TerminateTaskGroup
 from ._task_groups import force_terminate_task_group as force_terminate_task_group
+from ._types import ManagedStream as ManagedStream

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/src/asyncio_extensions/_compat.py

@@ -1,16 +1,21 @@
 import sys
-from collections.abc import Callable
 from contextvars import Context
-from typing import ParamSpec, TypedDict, TypeVar
+from typing import ParamSpec, TypeVar
 
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
 
+if sys.version_info >= (3, 15):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
 if sys.version_info >= (3, 12):
     from inspect import iscoroutinefunction, markcoroutinefunction
     from typing import override
 else:
     from asyncio import coroutines, iscoroutinefunction
+    from collections.abc import Callable
 
     from typing_extensions import override
 
@@ -29,7 +34,7 @@ else:
         pass
 
 
-class _CreateTaskParams(TypedDict, total=False):
+class _CreateTaskParams(TypedDict, total=False, closed=True):
     """Parameters for creating a task in a TaskGroup."""
 
     name: str | None

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/src/asyncio_extensions/_iterators.py

@@ -2,27 +2,18 @@
 
 import asyncio
 import sys
-from collections.abc import AsyncGenerator, AsyncIterable, AsyncIterator, Callable, Iterable
-from contextlib import AbstractAsyncContextManager, AsyncExitStack, aclosing, asynccontextmanager
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import AsyncExitStack, aclosing, asynccontextmanager
 from functools import wraps
-from typing import ParamSpec, TypeAlias, TypeVar
+from typing import Any, ParamSpec, TypeVar
 
 from ._compat import QueueShutDown, sentinel
 from ._sync import asyncify_iterable
 from ._task_groups import TaskGroup
+from ._types import AnyIterable, ManagedStream
 
 T = TypeVar("T")
 P = ParamSpec("P")
-ManagedStream: TypeAlias = AbstractAsyncContextManager[AsyncIterator[T]]
-"""An async context manager that yields an :class:`~collections.abc.AsyncIterator`.
-
-This is the return type of :func:`safe_gen` and :func:`merge_iterables`, and the
-accepted parameter type of :func:`flatten_stream`.  Use it to annotate functions
-that return a context-managed async stream::
-
-    def my_stream() -> ManagedStream[int]:
-        ...
-"""
 
 if sys.version_info >= (3, 13):
     STOP = sentinel("STOP")
@@ -78,7 +69,7 @@ async def iterate_queue(queue: asyncio.Queue[T]) -> AsyncGenerator[T]:
             queue.task_done()
 
 
-async def fill_queue(itr: AsyncIterable[T] | Iterable[T], queue: asyncio.Queue[T]) -> None:
+async def fill_queue(itr: AnyIterable[T], queue: asyncio.Queue[T]) -> None:
     """Fill *queue* with all items from *itr*.
 
     Accepts both sync and async iterables and puts each item into *queue*,
@@ -96,7 +87,7 @@ async def fill_queue(itr: AsyncIterable[T] | Iterable[T], queue: asyncio.Queue[T
         await queue.put(it)
 
 
-async def drain(itr: AsyncIterable[T] | Iterable[T]) -> int:
+async def drain(itr: AnyIterable[T]) -> int:
     """Consume the remaining items from *itr* and return the count drained.
 
     Accepts both sync and async iterables.
@@ -119,9 +110,7 @@ async def drain(itr: AsyncIterable[T] | Iterable[T]) -> int:
 
 
 @asynccontextmanager
-async def merge_iterables(
-    *itrs: AsyncIterable[T] | Iterable[T],
-) -> AsyncGenerator[AsyncGenerator[T]]:
+async def merge_iterables(*itrs: AnyIterable[T]) -> AsyncGenerator[AsyncGenerator[T]]:
     """Merge multiple iterables into a single async stream.
 
     Feeds all *itrs* into a shared queue concurrently and yields a single
@@ -203,6 +192,7 @@ def safe_gen(fn: Callable[P, AsyncGenerator[T]]) -> Callable[P, ManagedStream[T]
                 await asyncio.sleep(10)
                 yield i
 
+
         async with iterate_slowly(5) as stream:
             async for item in stream:
                 print(item)
@@ -223,7 +213,7 @@ def safe_gen(fn: Callable[P, AsyncGenerator[T]]) -> Callable[P, ManagedStream[T]
     return decorator
 
 
-async def flatten_stream(ctx: ManagedStream[T]) -> AsyncIterator[T]:
+async def flatten_stream(ctx: ManagedStream[T]) -> AsyncGenerator[T]:
     """Iterate a context-managed stream without an explicit ``async with`` block.
 
     Enters *ctx*, iterates the resulting async iterator, and yields each item
@@ -256,3 +246,50 @@ async def flatten_stream(ctx: ManagedStream[T]) -> AsyncIterator[T]:
                 yield it
     except* GeneratorExit:
         pass
+
+
+async def for_each_concurrent(
+    source: AnyIterable[T],
+    callback: Callable[[T], Awaitable[Any]],
+    concurrency: int,
+) -> None:
+    """Apply *callback* to each item in *source* with bounded concurrency.
+
+    Consumes *source* and calls ``await callback(item)`` for each item,
+    keeping at most *concurrency* calls running at the same time. Items are
+    processed in the order they arrive from *source*, but callbacks may
+    complete out of order.
+
+    Args:
+        source: The source iterable (sync or async) to consume.
+        callback: An async callable invoked once per item.
+        concurrency: Maximum number of concurrent callback invocations.
+            Must be greater than 0.
+
+    Raises:
+        ValueError: If *concurrency* is not greater than 0.
+
+    Example::
+
+        async def fetch(url: str) -> None: ...
+
+
+        await for_each_concurrent(urls, fetch, concurrency=10)
+    """
+    if concurrency <= 0:
+        msg = f"concurrency must be greater than 0, got {concurrency!r}"
+        raise ValueError(msg)
+
+    queue: asyncio.Queue[T] = asyncio.Queue(concurrency)
+
+    async def worker() -> None:
+        async for item in iterate_queue(queue):
+            await callback(item)
+
+    async with TaskGroup() as tg:
+        for _ in range(concurrency):
+            tg.create_task(worker())
+
+        await fill_queue(source, queue)
+        await queue.join()
+        tg.cancel()

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/src/asyncio_extensions/_task_groups.py

@@ -4,7 +4,7 @@ import asyncio
 import sys
 from collections.abc import Coroutine
 from types import TracebackType
-from typing import Never, TypeVar, Unpack
+from typing import Any, Never, TypeVar, Unpack
 
 from ._compat import CreateTaskParams, override
 
@@ -67,7 +67,7 @@ class LimitedTaskGroup(TaskGroup):
     @override
     def create_task(
         self,
-        coro: Coroutine[None, None, T],
+        coro: Coroutine[Any, Any, T],
         **kwargs: Unpack[CreateTaskParams],
     ) -> asyncio.Task[T]:
         """Schedule *coro* as a task, subject to the concurrency limit.
@@ -78,5 +78,4 @@ class LimitedTaskGroup(TaskGroup):
         Returns:
             The created :class:`asyncio.Task`.
         """
-        # pyrefly: ignore [open-unpacking]
         return super().create_task(self._task_wrapper(coro), **kwargs)

asyncio_extensions-0.4.0/src/asyncio_extensions/_types.py

@@ -0,0 +1,19 @@
+from collections.abc import AsyncIterable, AsyncIterator, Iterable
+from contextlib import AbstractAsyncContextManager
+from typing import ParamSpec, TypeAlias, TypeVar
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+ManagedStream: TypeAlias = AbstractAsyncContextManager[AsyncIterator[T]]
+"""An async context manager that yields an :class:`~collections.abc.AsyncIterator`.
+
+This is the return type of :func:`safe_gen` and :func:`merge_iterables`, and the
+accepted parameter type of :func:`flatten_stream`.  Use it to annotate functions
+that return a context-managed async stream::
+
+    def my_stream() -> ManagedStream[int]:
+        ...
+"""
+
+AnyIterable: TypeAlias = AsyncIterable[T] | Iterable[T]

asyncio_extensions-0.4.0/tests/__init__.py

@@ -0,0 +1,2 @@
+async def noop(*_: object) -> None:
+    """Do nothing."""

{asyncio_extensions-0.3.2 → asyncio_extensions-0.4.0}/tests/test_iterators.py

@@ -3,6 +3,7 @@ import sys
 from collections.abc import AsyncGenerator
 from contextlib import aclosing
 from itertools import count
+from typing import Any
 
 import pytest
 
@@ -12,12 +13,15 @@ from asyncio_extensions._iterators import (
     drain,
     fill_queue,
     flatten_stream,
+    for_each_concurrent,
     iterate_queue,
     merge_iterables,
     merge_streams,
     safe_gen,
 )
 
+from . import noop
+
 pytestmark = pytest.mark.asyncio
 
 
@@ -200,14 +204,15 @@ async def test_merge_iterables_single_source_yields_all_items() -> None:
 
 
 async def test_merge_iterables_empty_sources_yields_nothing() -> None:
-    async with merge_iterables([], []) as stream:
+    given: list[Any] = []
+    async with merge_iterables(given, []) as stream:
         results = [item async for item in stream]
 
     assert results == []
 
 
 async def test_merge_iterables_no_sources_yields_nothing() -> None:
-    async with merge_iterables() as stream:
+    async with merge_iterables() as stream:  # type: ignore[var-annotated]
         results = [item async for item in stream]
 
     assert results == []
@@ -365,7 +370,8 @@ async def test_flatten_stream_yields_all_items() -> None:
 
 
 async def test_flatten_stream_empty_stream_yields_nothing() -> None:
-    results = [item async for item in flatten_stream(merge_iterables([]))]
+    given: list[Any] = []
+    results = [item async for item in flatten_stream(merge_iterables(given))]
 
     assert results == []
 
@@ -411,3 +417,81 @@ async def test_flatten_stream_safe_gen_closed_on_early_exit() -> None:
     await stream.aclose()
 
     assert closed
+
+
+# for_each_concurrent
+
+
+async def test_for_each_concurrent_zero_concurrency_raises() -> None:
+    with pytest.raises(ValueError, match="concurrency"):
+        await for_each_concurrent([], noop, 0)
+
+
+async def test_for_each_concurrent_negative_concurrency_raises() -> None:
+    with pytest.raises(ValueError, match="concurrency"):
+        await for_each_concurrent([], noop, -1)
+
+
+async def test_for_each_concurrent_sync_iterable_calls_callback_for_each_item() -> None:
+    results: list[int] = []
+
+    async def callback(item: int) -> None:
+        results.append(item)
+
+    await for_each_concurrent([1, 2, 3], callback, concurrency=2)
+
+    assert sorted(results) == [1, 2, 3]
+
+
+async def test_for_each_concurrent_async_iterable_calls_callback_for_each_item() -> None:
+    async def source() -> AsyncGenerator[int]:
+        for v in [1, 2, 3]:
+            yield v
+
+    results: list[int] = []
+
+    async def callback(item: int) -> None:
+        results.append(item)
+
+    await for_each_concurrent(source(), callback, concurrency=2)
+
+    assert sorted(results) == [1, 2, 3]
+
+
+async def test_for_each_concurrent_empty_source_completes_without_calling_callback() -> None:
+    called = False
+
+    async def callback(_: int) -> None:
+        nonlocal called
+        called = True
+
+    await for_each_concurrent([], callback, concurrency=2)
+
+    assert not called
+
+
+async def test_for_each_concurrent_respects_concurrency_limit() -> None:
+    active = 0
+    max_active = 0
+
+    async def callback(_: int) -> None:
+        nonlocal active, max_active
+        active += 1
+        max_active = max(max_active, active)
+        await checkpoint()
+        active -= 1
+
+    await for_each_concurrent(range(10), callback, concurrency=3)
+
+    assert max_active <= 3  # noqa: PLR2004
+
+
+async def test_for_each_concurrent_concurrency_one_processes_serially() -> None:
+    order: list[int] = []
+
+    async def callback(item: int) -> None:
+        order.append(item)
+
+    await for_each_concurrent([1, 2, 3], callback, concurrency=1)
+
+    assert order == [1, 2, 3]

asyncio_extensions-0.3.2/tests/__init__.py

@@ -1,2 +0,0 @@
-async def noop() -> None:
-    """Do nothing."""