asyncio-extensions 0.0.1__tar.gz

asyncio_extensions-0.0.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+  - package-ecosystem: "devcontainers"
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: weekly

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

@@ -0,0 +1,33 @@
+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.1/.github/workflows/tests.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Run linters
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Setup Hatch
+        run: pipx install hatch
+
+      - name: Run static analysis
+        run: hatch fmt --check
+
+      - name: Run type checking
+        run: hatch run mypy src/asyncio_extensions
+
+  tests:
+    name: Run tests on ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup Hatch
+        run: pipx install hatch
+
+      - name: Run tests
+        run: |
+          hatch test -i py=${{ matrix.python-version }} --cover

asyncio_extensions-0.0.1/.gitignore

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

asyncio_extensions-0.0.1/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Christian Hartung <6785871+hartungstenio@users.noreply.github.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

asyncio_extensions-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: asyncio-extensions
+Version: 0.0.1
+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.1/README.md

@@ -0,0 +1,21 @@
+# 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.1/pyproject.toml

@@ -0,0 +1,154 @@
+[project]
+name = "asyncio-extensions"
+description = "Some (maybe) useful extensions for asyncio"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [
+  { name = "Christian Hartung", email = "6785871+hartungstenio@users.noreply.github.com" },
+]
+keywords = ["asyncio", "tasks"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+dynamic = ["version"]
+
+[project.urls]
+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 = [
+  "faker",
+  "mypy",
+  "pre-commit",
+  "pytest",
+  "pytest-asyncio",
+  "pytest-cov",
+]
+
+[build-system]
+requires = ["hatch-vcs", "hatchling"]
+build-backend = "hatchling.build"
+
+[tool.coverage.run]
+source_pkgs = ["asyncio_extensions", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/asyncio_extensions/__about__.py",
+]
+
+[tool.coverage.paths]
+asyncio_extensions = [
+  "src/asyncio_extensions",
+  "*/asyncio-extensions/src/asyncio_extensions"
+]
+tests = ["tests", "*/asyncio-extensions/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.envs.default]
+dependency-groups = ["dev"]
+
+[tool.hatch.envs.hatch-static-analysis]
+config-path = "none"
+dependencies = ["ruff==0.14.*"]
+
+[tool.hatch.envs.hatch-test]
+extra-dependencies = [
+  "faker",
+  "pytest-asyncio",
+]
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.11", "3.12", "3.13", "3.14"]
+
+[tool.pytest]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  "A",
+  "ANN",
+  "ASYNC",
+  "B",
+  "BLE",
+  "C4",
+  "C90",
+  "COM818",
+  "D",
+  "DJ",
+  "DTZ",
+  "E",
+  "EM",
+  "ERA",
+  "EXE",
+  "F",
+  "FBT",
+  "FLY",
+  "FURB",
+  "G",
+  "I",
+  "ICN",
+  "INT",
+  "ISC",
+  "LOG",
+  "N",
+  "PERF",
+  "PGH",
+  "PIE",
+  "PL",
+  "PT",
+  "PTH",
+  "PYI",
+  "RET",
+  "RSE",
+  "RUF",
+  "S",
+  "SIM",
+  "SLF",
+  "SLOT",
+  "T10",
+  "T20",
+  "TC",
+  "TD",
+  "TID",
+  "TRY",
+  "UP",
+  "W",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["D", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"

asyncio_extensions-0.0.1/src/asyncio_extensions/__init__.py

@@ -0,0 +1,12 @@
+"""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.1/src/asyncio_extensions/taskgroups.py

@@ -0,0 +1,60 @@
+"""Extensions to interact with TaskGroups."""
+
+import asyncio
+from collections.abc import Coroutine
+from contextlib import AbstractAsyncContextManager
+from contextvars import Context
+from types import TracebackType
+from typing import Any, Never, Self, 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(AbstractAsyncContextManager["TaskGroup"]):
+    """A version of asyncio.TaskGroup with a cancel method."""
+
+    def __init__(self) -> None:  # noqa: D107
+        self.tasks = asyncio.TaskGroup()
+
+    async def __aenter__(self) -> Self:  # noqa: D105
+        await self.tasks.__aenter__()
+        return self
+
+    async def __aexit__(  # noqa: D105
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        try:  # noqa: SIM105
+            await self.tasks.__aexit__(exc_type, exc_value, traceback)
+        except* TerminateTaskGroup:
+            pass
+
+        return None
+
+    def create_task(
+        self,
+        coro: Coroutine[Any, Any, T],
+        *,
+        name: str | None = None,
+        context: Context | None = None,
+    ) -> asyncio.Task[T]:
+        """Create a new task in this group and return it."""
+        return self.tasks.create_task(coro, name=name, context=context)
+
+    def cancel(self) -> None:
+        """Cancel any remaining task in the TaskGroup."""
+        self.create_task(force_terminate_task_group())

asyncio_extensions-0.0.1/src/asyncio_extensions/utils.py

@@ -0,0 +1,27 @@
+"""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.1/tests/test_taskgroups.py

@@ -0,0 +1,54 @@
+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

asyncio_extensions-0.0.1/tests/test_utils.py

@@ -0,0 +1,38 @@
+import asyncio
+
+import pytest
+from faker import Faker
+
+from asyncio_extensions.utils import checkpoint, sleep_forever
+
+from .utils import noop
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_checkpoint() -> None:
+    async with asyncio.TaskGroup() as tg:
+        task = tg.create_task(noop())
+
+        await checkpoint()
+
+        assert task.done() is True
+
+
+async def test_sleep_forever(faker: Faker) -> None:
+    with pytest.raises(TimeoutError):
+        async with asyncio.timeout(faker.random_int(1, 10)):
+            await sleep_forever()
+
+
+async def test_sleep_forever_cycles_event_loop(faker: Faker) -> None:
+    with pytest.raises(TimeoutError):  # noqa: PT012
+        async with (
+            asyncio.timeout(faker.random_int(1, 10)),
+            asyncio.TaskGroup() as tg,
+        ):
+            tasks = [tg.create_task(asyncio.sleep(i)) for i in range(7)]
+            await sleep_forever()
+
+    assert all(t.done() for t in tasks)
+    assert not any(t.cancelled() for t in tasks)

asyncio_extensions-0.0.1/tests/utils.py

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