asyncio-extensions 0.0.2__tar.gz → 0.0.4__tar.gz

{asyncio_extensions-0.0.2 → asyncio_extensions-0.0.4}/.github/dependabot.yml

@@ -6,10 +6,6 @@
 
 version: 2
 updates:
-  - package-ecosystem: "devcontainers"
-    directory: "/"
-    schedule:
-      interval: weekly
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

asyncio_extensions-0.0.4/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Build & Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Install pypa/build
+        run: |
+          python -m pip install --upgrade pip build --user
+
+      - name: Build a binary wheel and a source tarball
+        run: python -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    environment:
+      name: release
+      url: https://pypi.org/p/asyncio-extensions
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.13.0

{asyncio_extensions-0.0.2 → asyncio_extensions-0.0.4}/.github/workflows/tests.yml

@@ -27,7 +27,7 @@ jobs:
           python-version: "3.13"
 
       - name: Setup Hatch
-        run: pipx install hatch
+        run: pipx  install --preinstall "virtualenv<21" hatch
 
       - name: Run static analysis
         run: hatch fmt --check
@@ -51,8 +51,20 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup Hatch
-        run: pipx install hatch
+        run: pipx  install --preinstall "virtualenv<21" hatch
 
       - name: Run tests
         run: |
-          hatch test -i py=${{ matrix.python-version }} --cover
+          hatch test -i py=${{ matrix.python-version }} --cover --junitxml=junit.xml
+
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          report_type: test_results
+          token: ${{ secrets.CODECOV_TOKEN }}

asyncio_extensions-0.0.4/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+dist/
+.coverage*
+coverage.xml
+junit.xml

asyncio_extensions-0.0.4/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-illegal-windows-names
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: destroyed-symlinks
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: forbid-submodules
+      - id: name-tests-test
+        args:
+          - --pytest-test-first
+      - id: no-commit-to-branch
+      - id: trailing-whitespace
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.9
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [pre-push]

asyncio_extensions-0.0.4/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+This project adheres to both [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## [UNRELEASED]
+
+### Added
+
+- `asyncify` function to wrap synchronous callables so they can be awaited, running them in a separate thread via `asyncio.to_thread`.
+
+## [0.0.3] - 2026-02-26
+
+### Added
+
+- This CHANGELOG file.
+- pre-commit config.
+- test coverage using Codecov
+- LimitedTaskGroup to execute tasks limiting concurrency
+- heartbeat function to run something at regular interval
+
+### Changed
+
+- Package building and publishing are run in separate jobs to avoid credential sharing.
+- Improved README
+
+## [0.0.2] - 2025-12-23
+
+### Changed
+
+- `TaskGroup` now inherits from `asyncio.TaskGroup`.
+
+## [0.0.1] - 2025-12-23
+
+### Added
+
+- `TaskGroup` subclass with a cancel method.
+- `checkpoint` function to yield control to the event loop.
+- `sleep_forever` function.
+
+[unreleased]: https://github.com/hartungstenio/asyncio-extensions/compare/0.0.3...HEAD
+[0.0.3]: https://github.com/hartungstenio/asyncio-extensions/compare/0.0.2...0.0.3
+[0.0.2]: https://github.com/hartungstenio/asyncio-extensions/compare/0.0.1...0.0.2
+[0.0.1]: https://github.com/hartungstenio/asyncio-extensions/releases/tag/0.0.1

asyncio_extensions-0.0.4/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: asyncio-extensions
+Version: 0.0.4
+Summary: Some (maybe) useful extensions for asyncio
+Project-URL: Source, https://github.com/hartungstenio/asyncio-extensions
+Project-URL: Changelog, https://github.com/hartungstenio/asyncio-extensions/blob/main/CHANGELOG.md
+Project-URL: ReleaseNotes, https://github.com/hartungstenio/asyncio-extensions/releases
+Project-URL: Documentation, https://github.com/hartungstenio/asyncio-extensions#readme
+Project-URL: Issues, https://github.com/hartungstenio/asyncio-extensions/issues
+Author-email: Christian Hartung <6785871+hartungstenio@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: asyncio,tasks
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: typing-extensions; python_version < '3.12'
+Description-Content-Type: text/markdown
+
+# asyncio-extensions
+
+[![PyPI - Version](https://img.shields.io/pypi/v/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
+[![codecov](https://codecov.io/github/hartungstenio/asyncio-extensions/graph/badge.svg?token=1MEZ4NBUJH)](https://codecov.io/github/hartungstenio/asyncio-extensions)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/hartungstenio/asyncio-extensions/main.svg)](https://results.pre-commit.ci/latest/github/hartungstenio/asyncio-extensions/main)
+
+-----
+
+## Installation
+
+```console
+pip install asyncio-extensions
+```
+
+## Usage
+
+### TaskGroup
+
+`asyncio-extensions` provides a cancellable version of AsyncIO's `TaskGroup`.
+
+```python
+import asyncio
+
+from asyncio_extensions import TaskGroup
+
+queue = asyncio.Queue()
+async with TaskGroup() as tg:
+    for _ in range(10):
+        tg.create_task(consume_from_queue(queue))
+
+    await add_to_queue(queue)
+    await queue.join()
+    tg.cancel()
+```
+
+#### LimitedTaskGroup
+
+A version of `TaskGroup` that limits the number of concurrently running tasks.
+
+```python
+import asyncio
+
+from asyncio_extensions import LimitedTaskGroup
+
+queue = asyncio.Queue()
+async with LimitedTaskGroup(3) as tg:
+    for _ in range(50):
+        tg.create_task(some_expensive_operation(queue))
+
+    await add_to_queue(queue)
+    await queue.join()
+    tg.cancel()
+```
+
+### checkpoint
+
+The `checkpoint` function yields control to the event loop. It is a more elegant approach to do-nothing tasks, giving other tasks a chance to run.
+
+```python
+from asyncio_extensions import checkpoint
+
+class DummyChannel:
+    async def send_message(self, message):
+        await checkpoint()
+```
+
+### sleep_forever
+
+The `sleep_forever` function never returns. It simply keeps yielding control to the event loop.
+
+```python
+from asyncio_extensions import sleep_forever
+
+class DummyChannel:
+    async def receive_message(self):
+        await sleep_forever()
+```
+
+### heartbeat
+
+The `heartbeat` function runs a given callable at a regular interval.
+
+```python
+from asyncio_extensions import heartbeat
+
+async def ping():
+    pass
+
+async with TaskGroup() as tg:
+    tg.create_task(heartbeat(5, ping))
+
+    await some_long_running_process()
+```
+
+### asyncify
+
+The `asyncify` function ensures a callable can be awaited. If the callable is already a coroutine function, it is returned as-is. Otherwise, it is wrapped so that calls run in a separate thread.
+
+```python
+from asyncio_extensions import asyncify
+
+def blocking_read(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+
+async def main():
+    content = await asyncify(blocking_read)("data.txt")
+```
+
+It can also be used as a decorator:
+
+```python
+from asyncio_extensions import asyncify
+
+@asyncify
+def blocking_read(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+
+async def main():
+    content = await blocking_read("data.txt")
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+
+`asyncio-extensions` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

asyncio_extensions-0.0.4/README.md

@@ -0,0 +1,134 @@
+# asyncio-extensions
+
+[![PyPI - Version](https://img.shields.io/pypi/v/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
+[![codecov](https://codecov.io/github/hartungstenio/asyncio-extensions/graph/badge.svg?token=1MEZ4NBUJH)](https://codecov.io/github/hartungstenio/asyncio-extensions)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/hartungstenio/asyncio-extensions/main.svg)](https://results.pre-commit.ci/latest/github/hartungstenio/asyncio-extensions/main)
+
+-----
+
+## Installation
+
+```console
+pip install asyncio-extensions
+```
+
+## Usage
+
+### TaskGroup
+
+`asyncio-extensions` provides a cancellable version of AsyncIO's `TaskGroup`.
+
+```python
+import asyncio
+
+from asyncio_extensions import TaskGroup
+
+queue = asyncio.Queue()
+async with TaskGroup() as tg:
+    for _ in range(10):
+        tg.create_task(consume_from_queue(queue))
+
+    await add_to_queue(queue)
+    await queue.join()
+    tg.cancel()
+```
+
+#### LimitedTaskGroup
+
+A version of `TaskGroup` that limits the number of concurrently running tasks.
+
+```python
+import asyncio
+
+from asyncio_extensions import LimitedTaskGroup
+
+queue = asyncio.Queue()
+async with LimitedTaskGroup(3) as tg:
+    for _ in range(50):
+        tg.create_task(some_expensive_operation(queue))
+
+    await add_to_queue(queue)
+    await queue.join()
+    tg.cancel()
+```
+
+### checkpoint
+
+The `checkpoint` function yields control to the event loop. It is a more elegant approach to do-nothing tasks, giving other tasks a chance to run.
+
+```python
+from asyncio_extensions import checkpoint
+
+class DummyChannel:
+    async def send_message(self, message):
+        await checkpoint()
+```
+
+### sleep_forever
+
+The `sleep_forever` function never returns. It simply keeps yielding control to the event loop.
+
+```python
+from asyncio_extensions import sleep_forever
+
+class DummyChannel:
+    async def receive_message(self):
+        await sleep_forever()
+```
+
+### heartbeat
+
+The `heartbeat` function runs a given callable at a regular interval.
+
+```python
+from asyncio_extensions import heartbeat
+
+async def ping():
+    pass
+
+async with TaskGroup() as tg:
+    tg.create_task(heartbeat(5, ping))
+
+    await some_long_running_process()
+```
+
+### asyncify
+
+The `asyncify` function ensures a callable can be awaited. If the callable is already a coroutine function, it is returned as-is. Otherwise, it is wrapped so that calls run in a separate thread.
+
+```python
+from asyncio_extensions import asyncify
+
+def blocking_read(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+
+async def main():
+    content = await asyncify(blocking_read)("data.txt")
+```
+
+It can also be used as a decorator:
+
+```python
+from asyncio_extensions import asyncify
+
+@asyncify
+def blocking_read(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+
+async def main():
+    content = await blocking_read("data.txt")
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## License
+
+`asyncio-extensions` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

asyncio_extensions-0.0.4/codecov.yml

@@ -0,0 +1,13 @@
+coverage:
+  range: 80...95
+  round: down
+  precision: 2
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 0%
+    patch:
+      default:
+        target: auto
+        threshold: 0%

{asyncio_extensions-0.0.2 → asyncio_extensions-0.0.4}/pyproject.toml

@@ -23,13 +23,17 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
   "Typing :: Typed",
 ]
-dependencies = []
+dependencies = [
+  "typing-extensions; python_version < '3.12'",
+]
 dynamic = ["version"]
 
 [project.urls]
+Source = "https://github.com/hartungstenio/asyncio-extensions"
+Changelog = "https://github.com/hartungstenio/asyncio-extensions/blob/main/CHANGELOG.md"
+ReleaseNotes = "https://github.com/hartungstenio/asyncio-extensions/releases"
 Documentation = "https://github.com/hartungstenio/asyncio-extensions#readme"
 Issues = "https://github.com/hartungstenio/asyncio-extensions/issues"
-Source = "https://github.com/hartungstenio/asyncio-extensions"
 
 [dependency-groups]
 dev = [
@@ -86,6 +90,12 @@ extra-dependencies = [
 [[tool.hatch.envs.hatch-test.matrix]]
 python = ["3.11", "3.12", "3.13", "3.14"]
 
+[tool.hatch.envs.hatch-test.scripts]
+run = "pytest{env:HATCH_TEST_ARGS:} {args}"
+run-cov = "coverage run -m pytest{env:HATCH_TEST_ARGS:} {args}"
+cov-combine = "coverage combine"
+cov-report = "coverage xml"
+
 [tool.pytest]
 asyncio_default_fixture_loop_scope = "function"
 

asyncio_extensions-0.0.4/src/asyncio_extensions/__init__.py

@@ -0,0 +1,21 @@
+"""Utility functions and extensions for AsyncIO."""
+
+from .bridge import asyncify
+from .taskgroups import (
+    LimitedTaskGroup,
+    TaskGroup,
+    TerminateTaskGroup,
+    force_terminate_task_group,
+)
+from .utils import checkpoint, heartbeat, sleep_forever
+
+__all__ = [
+    "LimitedTaskGroup",
+    "TaskGroup",
+    "TerminateTaskGroup",
+    "asyncify",
+    "checkpoint",
+    "force_terminate_task_group",
+    "heartbeat",
+    "sleep_forever",
+]

asyncio_extensions-0.0.4/src/asyncio_extensions/_compat.py

@@ -0,0 +1,30 @@
+import inspect
+import sys
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, TypeVar
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+def is_awaitable(
+    func: Callable[_P, _R] | Callable[_P, Awaitable[_R]],
+) -> TypeIs[Callable[_P, Awaitable[_R]]]:
+    return inspect.iscoroutinefunction(func)
+
+
+__all__ = [
+    "TypeIs",
+    "is_awaitable",
+    "override",
+]

asyncio_extensions-0.0.4/src/asyncio_extensions/bridge.py

@@ -0,0 +1,47 @@
+"""Utilities for bridging synchronous and asynchronous code."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar, overload
+
+from ._compat import is_awaitable
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+@overload
+def asyncify(func: Callable[_P, Awaitable[_R]], /) -> Callable[_P, Awaitable[_R]]: ...
+
+
+@overload
+def asyncify(func: Callable[_P, _R], /) -> Callable[_P, Awaitable[_R]]: ...
+
+
+def asyncify(
+    func: Callable[_P, _R] | Callable[_P, Awaitable[_R]], /
+) -> Callable[_P, Awaitable[_R]]:
+    """Ensure that a callable can be awaited.
+
+    If ``func`` is already a coroutine function, it is returned as-is.
+    Otherwise, it is wrapped with :func:`asyncio.to_thread`, so that calls to
+    the returned callable will run ``func`` in a separate thread and return an
+    awaitable result.
+
+
+    Args:
+        func: A callable that is either synchronous or already a coroutine function.
+
+    Returns:
+        A callable with the same signature as ``func`` that returns an
+        :class:`~collections.abc.Awaitable`.
+    """
+    if is_awaitable(func):
+        return func
+
+    @wraps(func)
+    async def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        return await asyncio.to_thread(func, *args, **kwargs)
+
+    return wrapper

asyncio_extensions-0.0.4/src/asyncio_extensions/taskgroups.py

@@ -0,0 +1,93 @@
+"""Extensions to interact with TaskGroups."""
+
+import asyncio
+import sys
+from collections.abc import Coroutine
+from contextvars import Context
+from types import TracebackType
+from typing import Any, Never, TypedDict, TypeVar, Unpack
+
+from ._compat import override
+
+T = TypeVar("T")
+
+
+class _CreateTaskParams(TypedDict, total=False):
+    """Parameters for creating a task in a TaskGroup."""
+
+    name: str | None
+    context: Context | None
+
+
+if sys.version_info >= (3, 14):
+
+    class CreateTaskParams(_CreateTaskParams):
+        """Parameters for creating a task in a TaskGroup."""
+
+        eager_start: bool | None
+else:
+    CreateTaskParams = _CreateTaskParams
+
+
+class TerminateTaskGroup(BaseException):
+    """Signal to terminate a task group.
+
+    Technically not an exception, so inherits from `BaseException`.
+    """
+
+
+async def force_terminate_task_group() -> Never:
+    """Force termination of a task group."""
+    raise TerminateTaskGroup
+
+
+class TaskGroup(asyncio.TaskGroup):
+    """A version of asyncio.TaskGroup with a cancel method."""
+
+    async def __aexit__(  # noqa: D105
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:  # noqa: SIM105
+            await super().__aexit__(exc_type, exc_value, traceback)
+        except* TerminateTaskGroup:
+            pass
+
+    def cancel(self) -> None:
+        """Cancel any remaining task in the TaskGroup."""
+        self.create_task(force_terminate_task_group())
+
+
+class LimitedTaskGroup(TaskGroup):
+    """A TaskGroup that limits the number of concurrent tasks."""
+
+    def __init__(self, max_concurrent: int) -> None:
+        """Initialize the LimitedTaskGroup.
+
+        Args:
+            max_concurrent: Maximum number of concurrent tasks.
+        """
+        super().__init__()
+        self._semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def _task_wrapper(self, coro: Coroutine[Any, Any, T]) -> T:
+        async with self._semaphore:
+            return await coro
+
+    @override
+    def create_task(
+        self,
+        coro: Coroutine[Any, Any, T],
+        **kwargs: Unpack[CreateTaskParams],
+    ) -> asyncio.Task[T]:
+        """Create a task within the limited concurrency context.
+
+        Args:
+            coro: The coroutine to run as a task.
+
+        Returns:
+            The created asyncio Task.
+        """
+        return super().create_task(self._task_wrapper(coro), **kwargs)

asyncio_extensions-0.0.4/src/asyncio_extensions/utils.py

@@ -0,0 +1,49 @@
+"""Utility functions."""
+
+import asyncio
+from collections.abc import Awaitable, Callable, Generator
+from typing import Any, Never, ParamSpec, TypeVar
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+
+class YieldToEventLoop:
+    """Helper class to give control back to the event loop."""
+
+    def __await__(self) -> Generator[None, Any, None]:
+        """Yield control to the event loop."""
+        yield
+
+
+async def checkpoint() -> None:
+    """
+    Give control back to the eventloop.
+
+    This has the same effect of and asyncio.sleep(0), but it is more semantic
+    """
+    return await YieldToEventLoop()
+
+
+async def sleep_forever() -> Never:
+    """Sleeps forever."""
+    while True:
+        await YieldToEventLoop()
+
+
+async def noop(result: T) -> T:
+    """Give control back to the event loop once, then returns the given argument."""
+    await YieldToEventLoop()
+    return result
+
+
+async def heartbeat(
+    interval: float,
+    fn: Callable[P, Awaitable[T]],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> None:
+    """Run :arg:`fn` with the given args at regular interval."""
+    while True:
+        await asyncio.sleep(interval)
+        await fn(*args, **kwargs)

asyncio_extensions-0.0.4/tests/test_bridge.py

@@ -0,0 +1,106 @@
+import asyncio
+import threading
+from collections.abc import Awaitable
+
+import pytest
+
+from asyncio_extensions.bridge import asyncify
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_asyncify_sync_returns_awaitable() -> None:
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    result = asyncify(add)(1, 2)
+
+    assert isinstance(result, Awaitable)
+    assert await result == add(1, 2)
+
+
+async def test_asyncify_sync_runs_in_thread() -> None:
+    caller_thread = threading.current_thread()
+    func_thread: threading.Thread | None = None
+
+    def capture_thread() -> None:
+        nonlocal func_thread
+        func_thread = threading.current_thread()
+
+    await asyncify(capture_thread)()
+
+    assert func_thread is not None
+    assert func_thread is not caller_thread
+
+
+async def test_asyncify_sync_preserves_wraps_metadata() -> None:
+    def my_func() -> None:
+        """My docstring."""
+
+    wrapped = asyncify(my_func)
+
+    assert wrapped.__name__ == "my_func"
+    assert wrapped.__doc__ == "My docstring."
+
+
+async def test_asyncify_async_returns_same_function() -> None:
+    async def coro() -> int:
+        return 42
+
+    assert asyncify(coro) is coro
+
+
+async def test_asyncify_as_decorator_on_sync() -> None:
+    @asyncify
+    def multiply(a: int, b: int) -> int:
+        return a * b
+
+    result = await multiply(3, 4)
+
+    assert result == 12  # noqa: PLR2004
+
+
+async def test_asyncify_as_decorator_on_async() -> None:
+    @asyncify
+    async def subtract(a: int, b: int) -> int:
+        return a - b
+
+    result = await subtract(10, 3)
+
+    assert result == 7  # noqa: PLR2004
+
+
+async def test_asyncify_decorator_preserves_name() -> None:
+    @asyncify
+    def named_func() -> None:
+        """Has a name."""
+
+    assert named_func.__name__ == "named_func"
+    assert named_func.__doc__ == "Has a name."
+
+
+async def test_asyncify_decorator_runs_sync_in_thread() -> None:
+    caller_thread = threading.current_thread()
+    seen_thread: threading.Thread | None = None
+
+    @asyncify
+    def work() -> None:
+        nonlocal seen_thread
+        seen_thread = threading.current_thread()
+
+    await work()
+
+    assert seen_thread is not None
+    assert seen_thread is not caller_thread
+
+
+async def test_asyncify_decorator_concurrent_calls() -> None:
+    results: list[int] = []
+
+    @asyncify
+    def append(value: int) -> None:
+        results.append(value)
+
+    await asyncio.gather(append(1), append(2), append(3))
+
+    assert sorted(results) == [1, 2, 3]

asyncio_extensions-0.0.4/tests/test_taskgroups.py

@@ -0,0 +1,109 @@
+import asyncio
+import sys
+from contextvars import copy_context
+
+import pytest
+
+from asyncio_extensions import checkpoint
+from asyncio_extensions.taskgroups import (
+    LimitedTaskGroup,
+    TaskGroup,
+    TerminateTaskGroup,
+    force_terminate_task_group,
+)
+
+from . import noop
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_force_terminate_task_group() -> None:
+    with pytest.RaisesGroup(TerminateTaskGroup):
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(asyncio.sleep(1000))
+            tg.create_task(force_terminate_task_group())
+
+
+class TestTaskGroup:
+    async def test_runs_tasks(self) -> None:
+        async with TaskGroup() as tg:
+            tasks = [tg.create_task(noop()) for _ in range(10)]
+
+        assert all(t.done() for t in tasks)
+        assert not any(t.cancelled() for t in tasks)
+
+    async def test_cancel_with_running_task(self) -> None:
+        async with (
+            asyncio.timeout(1),
+            TaskGroup() as tg,
+        ):
+            task = tg.create_task(asyncio.sleep(10))
+            tg.cancel()
+        assert task.cancelled() is True
+
+    async def test_cancel_without_running_task(self) -> None:
+        async with TaskGroup() as tg:
+            tg.cancel()
+
+    async def test_cancel_with_done_task(self) -> None:
+        async with (
+            asyncio.timeout(1),
+            TaskGroup() as tg,
+        ):
+            task = tg.create_task(noop())
+            await task
+            tg.cancel()
+
+        assert task.done() is True
+        assert task.cancelled() is False
+
+
+class TestLimitedTaskGroup:
+    async def test_limits_concurrency(self) -> None:
+        max_concurrent = 3
+        current_concurrent = 0
+        peak_concurrent = 0
+
+        async def task() -> None:
+            nonlocal current_concurrent, peak_concurrent
+            current_concurrent += 1
+            peak_concurrent = max(peak_concurrent, current_concurrent)
+            await checkpoint()
+            current_concurrent -= 1
+
+        async with LimitedTaskGroup(max_concurrent=max_concurrent) as tg:
+            for _ in range(100):
+                tg.create_task(task())
+
+        assert peak_concurrent <= max_concurrent
+
+    async def test_create_task_params(self) -> None:
+        ctx = copy_context()
+        async with LimitedTaskGroup(max_concurrent=2) as tg:
+            task = tg.create_task(noop(), name="test_task", context=ctx)
+
+        assert task.get_name() == "test_task"
+
+        if sys.version_info >= (3, 12):
+            assert task.get_context() is ctx
+
+    @pytest.mark.skipif(sys.version_info < (3, 14), reason="Requires Python 3.14+")
+    async def test_create_task_params_eager(self) -> None:
+        ctx = copy_context()
+        async with LimitedTaskGroup(max_concurrent=2) as tg:
+            task = tg.create_task(
+                noop(),
+                name="test_task",
+                context=ctx,
+                eager_start=True,
+            )
+            tg.cancel()
+
+        assert task.get_name() == "test_task"
+        assert task.get_context() is ctx
+        assert task.done() is True
+
+    async def test_can_cancel(self) -> None:
+        tg = LimitedTaskGroup(max_concurrent=2)
+        assert hasattr(tg, "cancel")
+        assert callable(tg.cancel)

{asyncio_extensions-0.0.2 → asyncio_extensions-0.0.4}/tests/test_utils.py

@@ -1,11 +1,13 @@
 import asyncio
+from contextlib import suppress
+from unittest import mock
 
 import pytest
 from faker import Faker
 
-from asyncio_extensions.utils import checkpoint, sleep_forever
+from asyncio_extensions.utils import checkpoint, heartbeat, sleep_forever
 
-from .utils import noop
+from . import noop
 
 pytestmark = pytest.mark.asyncio
 
@@ -36,3 +38,12 @@ async def test_sleep_forever_cycles_event_loop(faker: Faker) -> None:
 
     assert all(t.done() for t in tasks)
     assert not any(t.cancelled() for t in tasks)
+
+
+async def test_heartbeat() -> None:
+    mock_fn = mock.AsyncMock()
+    with suppress(TimeoutError):
+        async with asyncio.timeout(5):
+            await heartbeat(1, mock_fn, 1, 2, name="a")
+
+    assert mock_fn.await_args_list == [mock.call(1, 2, name="a")] * 4

asyncio_extensions-0.0.2/.github/workflows/release.yml

@@ -1,33 +0,0 @@
-name: Build & Release
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: release
-      url: https://pypi.org/p/asyncio-extensions
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.x"
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip build
-
-      - name: Build package
-        run: python -m build
-
-      - name: Publish package
-        uses: pypa/gh-action-pypi-publish@v1.13.0

asyncio_extensions-0.0.2/.gitignore

@@ -1,2 +0,0 @@
-__pycache__/
-dist/

asyncio_extensions-0.0.2/PKG-INFO

@@ -1,47 +0,0 @@
-Metadata-Version: 2.4
-Name: asyncio-extensions
-Version: 0.0.2
-Summary: Some (maybe) useful extensions for asyncio
-Project-URL: Documentation, https://github.com/hartungstenio/asyncio-extensions#readme
-Project-URL: Issues, https://github.com/hartungstenio/asyncio-extensions/issues
-Project-URL: Source, https://github.com/hartungstenio/asyncio-extensions
-Author-email: Christian Hartung <6785871+hartungstenio@users.noreply.github.com>
-License-Expression: MIT
-License-File: LICENSE.txt
-Keywords: asyncio,tasks
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: AsyncIO
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python
-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: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# asyncio-extensions
-
-[![PyPI - Version](https://img.shields.io/pypi/v/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
-
------
-
-## Table of Contents
-
-- [Installation](#installation)
-- [License](#license)
-
-## Installation
-
-```console
-pip install asyncio-extensions
-```
-
-## License
-
-`asyncio-extensions` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

asyncio_extensions-0.0.2/README.md

@@ -1,21 +0,0 @@
-# asyncio-extensions
-
-[![PyPI - Version](https://img.shields.io/pypi/v/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/asyncio-extensions.svg)](https://pypi.org/project/asyncio-extensions)
-
------
-
-## Table of Contents
-
-- [Installation](#installation)
-- [License](#license)
-
-## Installation
-
-```console
-pip install asyncio-extensions
-```
-
-## License
-
-`asyncio-extensions` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

asyncio_extensions-0.0.2/src/asyncio_extensions/__init__.py

@@ -1,12 +0,0 @@
-"""Utility functions and extensions for AsyncIO."""
-
-from .taskgroups import TaskGroup, TerminateTaskGroup, force_terminate_task_group
-from .utils import checkpoint, sleep_forever
-
-__all__ = [
-    "TaskGroup",
-    "TerminateTaskGroup",
-    "checkpoint",
-    "force_terminate_task_group",
-    "sleep_forever",
-]

asyncio_extensions-0.0.2/src/asyncio_extensions/taskgroups.py

@@ -1,38 +0,0 @@
-"""Extensions to interact with TaskGroups."""
-
-import asyncio
-from types import TracebackType
-from typing import Never, TypeVar
-
-T = TypeVar("T")
-
-
-class TerminateTaskGroup(BaseException):
-    """Signal to terminate a task group.
-
-    Technically not an exception, so inherits from `BaseException`.
-    """
-
-
-async def force_terminate_task_group() -> Never:
-    """Force termination of a task group."""
-    raise TerminateTaskGroup
-
-
-class TaskGroup(asyncio.TaskGroup):
-    """A version of asyncio.TaskGroup with a cancel method."""
-
-    async def __aexit__(  # noqa: D105
-        self,
-        exc_type: type[BaseException] | None,
-        exc_value: BaseException | None,
-        traceback: TracebackType | None,
-    ) -> None:
-        try:  # noqa: SIM105
-            await super().__aexit__(exc_type, exc_value, traceback)
-        except* TerminateTaskGroup:
-            pass
-
-    def cancel(self) -> None:
-        """Cancel any remaining task in the TaskGroup."""
-        self.create_task(force_terminate_task_group())

asyncio_extensions-0.0.2/src/asyncio_extensions/utils.py

@@ -1,27 +0,0 @@
-"""Utility functions."""
-
-from collections.abc import Generator
-from typing import Any, Never
-
-
-class YieldToEventLoop:
-    """Helper class to give control back to the event loop."""
-
-    def __await__(self) -> Generator[None, Any, None]:
-        """Yield control to the event loop."""
-        yield
-
-
-async def checkpoint() -> None:
-    """
-    Give control back to the eventloop.
-
-    This has the same effect of and asyncio.sleep(0), but it is more semantic
-    """
-    return await YieldToEventLoop()
-
-
-async def sleep_forever() -> Never:
-    """Sleeps forever."""
-    while True:
-        await YieldToEventLoop()

asyncio_extensions-0.0.2/tests/test_taskgroups.py

@@ -1,54 +0,0 @@
-import asyncio
-
-import pytest
-
-from asyncio_extensions.taskgroups import (
-    TaskGroup,
-    TerminateTaskGroup,
-    force_terminate_task_group,
-)
-
-from .utils import noop
-
-pytestmark = pytest.mark.asyncio
-
-
-async def test_force_terminate_task_group() -> None:
-    with pytest.RaisesGroup(TerminateTaskGroup):
-        async with asyncio.TaskGroup() as tg:
-            tg.create_task(asyncio.sleep(1000))
-            tg.create_task(force_terminate_task_group())
-
-
-class TestTaskGroup:
-    async def test_runs_tasks(self) -> None:
-        async with TaskGroup() as tg:
-            tasks = [tg.create_task(noop()) for _ in range(10)]
-
-        assert all(t.done() for t in tasks)
-        assert not any(t.cancelled() for t in tasks)
-
-    async def test_cancel_with_running_task(self) -> None:
-        async with (
-            asyncio.timeout(1),
-            TaskGroup() as tg,
-        ):
-            task = tg.create_task(asyncio.sleep(10))
-            tg.cancel()
-        assert task.cancelled() is True
-
-    async def test_cancel_without_running_task(self) -> None:
-        async with TaskGroup() as tg:
-            tg.cancel()
-
-    async def test_cancel_with_done_task(self) -> None:
-        async with (
-            asyncio.timeout(1),
-            TaskGroup() as tg,
-        ):
-            task = tg.create_task(noop())
-            await task
-            tg.cancel()
-
-        assert task.done() is True
-        assert task.cancelled() is False