without-async 0.0.0__tar.gz → 0.0.7__tar.gz

without_async-0.0.7/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: without-async
+Version: 0.0.7
+Summary: The asyncio primitives without is built from: scoped background tasks, bounded concurrency, optional timeouts, and durations that cross an integer boundary.
+Author: Josh Karpel
+Author-email: Josh Karpel <josh.karpel@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# without-async
+
+The asyncio primitives the rest of `without` is built from. It sits below the
+substrate and speaks only the standard library: every signature here mentions
+`asyncio`, `collections.abc`, and `datetime` types and nothing else, which is
+what lets a package take it without taking the stream vocabulary along.
+
+- `background_task` starts a task on entry and cancels-then-awaits it on exit,
+  so nothing leaks past the `with` block.
+- `timeout` models "no limit" as `None` rather than as a sentinel float.
+- `limit_concurrency` drives work from a source only while below the limit, so a
+  lazy source is never advanced past it, over `cancel_futures` and
+  `as_async_iterator`.
+- `Seconds` and `Milliseconds` are counts, not durations: a boundary that
+  carries whole units declares one instead of a `timedelta` it would silently
+  truncate. These are the two symbols the package name does not cover; they sit
+  here because every duration they carry is one something waits out.
+- `without_async.testing` holds `yield_once` and `resolved_next_turn`, the two
+  deterministic single-turn helpers a test reaches for when the code it waits on
+  offers no signal of its own.
+
+See the [`without-async` guide](https://without.help/without-async/)
+(with the [API reference](https://without.help/without-async/reference/))
+for the full surface.

without_async-0.0.7/README.md

@@ -0,0 +1,24 @@
+# without-async
+
+The asyncio primitives the rest of `without` is built from. It sits below the
+substrate and speaks only the standard library: every signature here mentions
+`asyncio`, `collections.abc`, and `datetime` types and nothing else, which is
+what lets a package take it without taking the stream vocabulary along.
+
+- `background_task` starts a task on entry and cancels-then-awaits it on exit,
+  so nothing leaks past the `with` block.
+- `timeout` models "no limit" as `None` rather than as a sentinel float.
+- `limit_concurrency` drives work from a source only while below the limit, so a
+  lazy source is never advanced past it, over `cancel_futures` and
+  `as_async_iterator`.
+- `Seconds` and `Milliseconds` are counts, not durations: a boundary that
+  carries whole units declares one instead of a `timedelta` it would silently
+  truncate. These are the two symbols the package name does not cover; they sit
+  here because every duration they carry is one something waits out.
+- `without_async.testing` holds `yield_once` and `resolved_next_turn`, the two
+  deterministic single-turn helpers a test reaches for when the code it waits on
+  offers no signal of its own.
+
+See the [`without-async` guide](https://without.help/without-async/)
+(with the [API reference](https://without.help/without-async/reference/))
+for the full surface.

without_async-0.0.7/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "without-async"
+version = "0.0.7"
+description = "The asyncio primitives without is built from: scoped background tasks, bounded concurrency, optional timeouts, and durations that cross an integer boundary."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Josh Karpel"
+email = "josh.karpel@gmail.com"

without_async-0.0.7/pyproject.toml.orig

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "without-async"
+version = "0.0.7"
+description = "The asyncio primitives without is built from: scoped background tasks, bounded concurrency, optional timeouts, and durations that cross an integer boundary."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Josh Karpel", email = "josh.karpel@gmail.com" },
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []

without_async-0.0.7/src/without_async/__init__.py

@@ -0,0 +1,19 @@
+from without_async.durations import Milliseconds
+from without_async.durations import Seconds
+from without_async.tasks import as_async_iterator
+from without_async.tasks import background_task
+from without_async.tasks import cancel_futures
+from without_async.tasks import limit_concurrency
+from without_async.tasks import sleep_forever
+from without_async.tasks import timeout
+
+__all__ = [
+    "Milliseconds",
+    "Seconds",
+    "as_async_iterator",
+    "background_task",
+    "cancel_futures",
+    "limit_concurrency",
+    "sleep_forever",
+    "timeout",
+]

without_async-0.0.7/src/without_async/durations.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+# A `timedelta` is the right type for a duration everywhere in this workspace, and the
+# reason is exactly why these exist: it names its unit, so nothing downstream has to guess
+# whether a bare number meant seconds or milliseconds. What it cannot do is say that a
+# duration *survives* the boundary it is about to cross. A TCP keepalive knob carries whole
+# seconds, an SSE `retry:` line carries whole milliseconds, and SQLite's `busy_timeout`
+# carries whole milliseconds, so each one truncates whatever it is handed. Truncation is at
+# its worst where it is least visible: half a millisecond of `retry:` becomes `retry: 0`,
+# which does not mean "almost no wait", it means "reconnect immediately".
+#
+# So a boundary of that kind declares one of these instead, and what makes them worth
+# having is what they *cannot* hold. Each is a count, not a duration: there is no argument
+# to either constructor that names a finer unit, so a value too fine to cross is not a
+# value the type can be asked to carry. `of` is the one way an arbitrary `timedelta`
+# becomes one, and the only place the question "does this divide?" is ever asked.
+
+__all__ = [
+    "Milliseconds",
+    "Seconds",
+]
+
+
+def _counted(duration: timedelta, unit: timedelta, units: str) -> int:
+    count, remainder = divmod(duration, unit)
+    if remainder:
+        raise ValueError(f"a whole number of {units} cannot express {duration}")
+    return count
+
+
+@dataclass(frozen=True, slots=True)
+class Seconds:
+    """
+    A duration a boundary carrying integer seconds can express exactly.
+
+    The count itself, rather than a `timedelta` that happens to divide by one second: a
+    duration finer than the boundary carries is not something this can be constructed
+    from, so nothing downstream has a truncation left to do.
+
+    ```python
+    tcp_keepalive(idle=Seconds(60), interval=Seconds(10))
+    ```
+
+    `duration` is the `timedelta` back out, for arithmetic and for anything that takes a
+    plain duration. `of` is the way in from one, and the only place the question of
+    whether it divides is asked:
+
+    ```python
+    Seconds.of(settings.keepalive_idle)  # raises on a duration finer than a second
+    ```
+    """
+
+    count: int
+
+    @property
+    def duration(self) -> timedelta:
+        """The `timedelta` this count of seconds names."""
+        return timedelta(seconds=self.count)
+
+    @classmethod
+    def of(cls, duration: timedelta) -> Seconds:
+        """Parse a `timedelta` into a count of seconds, refusing a finer duration."""
+        return cls(_counted(duration, timedelta(seconds=1), "seconds"))
+
+
+@dataclass(frozen=True, slots=True)
+class Milliseconds:
+    """
+    A duration a boundary carrying integer milliseconds can express exactly.
+
+    The millisecond counterpart of `Seconds`, with the same shape: a count in, `duration`
+    back out, and `of` to parse one from a `timedelta`.
+
+    ```python
+    yield Retry(Milliseconds.of(timedelta(seconds=30)))
+    ```
+    """
+
+    count: int
+
+    @property
+    def duration(self) -> timedelta:
+        """The `timedelta` this count of milliseconds names."""
+        return timedelta(milliseconds=self.count)
+
+    @classmethod
+    def of(cls, duration: timedelta) -> Milliseconds:
+        """Parse a `timedelta` into a count of milliseconds, refusing a finer duration."""
+        return cls(_counted(duration, timedelta(milliseconds=1), "milliseconds"))

without_async-0.0.7/src/without_async/tasks.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterable
+from collections.abc import AsyncIterator
+from collections.abc import Awaitable
+from collections.abc import Coroutine
+from collections.abc import Iterable
+from contextlib import asynccontextmanager
+from contextlib import suppress
+from datetime import timedelta
+
+
+@asynccontextmanager
+async def timeout(duration: timedelta | None) -> AsyncIterator[None]:
+    """
+    Bound the `with` block by `duration`, or leave it unbounded when `None`.
+
+    A `timedelta`-typed, nullable wrapper over `asyncio.timeout`: `None` disables the
+    bound (an always-open context), and a duration raises `TimeoutError` if the block
+    outlives it. Modelling "no limit" as `None` keeps that choice a first-class value at
+    the call site, rather than a sentinel float threaded through the same parameter.
+    """
+    if duration is None:
+        yield
+        return
+    async with asyncio.timeout(duration.total_seconds()):
+        yield
+
+
+async def sleep_forever() -> None:
+    """
+    Suspend the current task until it is cancelled.
+
+    The idiom for a coroutine whose job is to stay alive until its surrounding
+    scope tears it down: a server's run loop holding a bound socket open, a
+    process that should idle until signalled. It awaits a future that never
+    resolves, so it consumes nothing and ends only on cancellation.
+    """
+    await asyncio.get_running_loop().create_future()
+
+
+async def cancel_futures[T](futures: Iterable[asyncio.Future[T] | None]) -> None:
+    """
+    Cancel every future, then await them all so their teardown completes.
+
+    Two phases on purpose: cancelling the whole set *before* awaiting any of them
+    lets them tear down concurrently, instead of serially cancelling and waiting
+    for one at a time. `None` entries are skipped, so a caller holding an optional
+    task (`task: asyncio.Task | None`) can pass it without a guard. The futures are
+    materialized first, so a caller may pass a live set the awaits will mutate. Each
+    future's own `CancelledError` is suppressed; any other exception it raises during
+    teardown propagates, which also ends the loop, so the futures behind it in the set
+    are cancelled but never awaited. That is the right order for a set of *pending*
+    futures, where nothing has an exception to raise; pass one that may already hold a
+    failure and the ones behind it lose their teardown to it. Filter to what is still
+    running when the set can contain both.
+    """
+    present = [future for future in futures if future is not None]
+    for future in present:
+        future.cancel()
+    for future in present:
+        with suppress(asyncio.CancelledError):
+            await future
+
+
+@asynccontextmanager
+async def background_task[T](coro: Coroutine[object, object, T]) -> AsyncIterator[asyncio.Task[T]]:
+    """
+    Run `coro` as a task for the duration of the `with` block.
+
+    The task is started on entry and cancelled (then awaited) on exit, so it is
+    bounded by the block and never leaks. If it finishes on its own with an
+    exception, that surfaces when the block exits.
+    """
+    task = asyncio.create_task(coro)
+    try:
+        yield task
+    finally:
+        await cancel_futures([task])
+
+
+async def as_async_iterator[T](items: AsyncIterable[T] | Iterable[T]) -> AsyncIterator[T]:
+    """
+    Normalize a sync or async iterable into a single async iterator.
+
+    Lets code that consumes via `async for`/`anext` accept either kind without
+    branching on the iteration protocol at every use.
+    """
+    if isinstance(items, AsyncIterable):
+        async for item in items:
+            yield item
+    else:
+        for item in items:
+            yield item
+
+
+async def limit_concurrency[T](
+    aws: AsyncIterable[Awaitable[T]] | Iterable[Awaitable[T]],
+    limit: int,
+) -> AsyncIterator[asyncio.Future[T]]:
+    """
+    Run awaitables from `aws` with at most `limit` in flight, yielding each as it finishes.
+
+    A bounded-concurrency driver: it pulls the next awaitable from `aws` only
+    while fewer than `limit` are already running. So a *lazy* source (an async
+    generator that produces each unit of work on demand) is never advanced past
+    the limit. That is what lets it gate a side-effecting source: an accept loop
+    whose generator awaits `socket.accept()` only when pulled will never accept
+    more connections than it can serve.
+
+    Each completed awaitable is yielded as a `Future`; call `.result()` on it to
+    read the value or re-raise its exception. On early exit or cancellation, any
+    still-running awaitables are cancelled and awaited, so none outlive the
+    iteration.
+
+    `limit` must be at least 1; a non-positive limit is a `ValueError`, since it
+    could only ever stall the source rather than run it.
+
+    Adapted from [Limiting concurrency in
+    asyncio](https://death.andgravity.com/limit-concurrency).
+    """
+    if limit < 1:
+        raise ValueError(f"limit must be at least 1, but got {limit}")
+    source = as_async_iterator(aws)
+    ended = False  # pragma: no mutate - only ever read as a bool, never identity-compared
+    pending: set[asyncio.Future[T]] = set()
+    try:
+        while pending or not ended:
+            while len(pending) < limit and not ended:
+                try:
+                    aw = await anext(source)
+                except StopAsyncIteration:
+                    ended = True
+                else:
+                    pending.add(asyncio.ensure_future(aw))
+            if not pending:
+                return
+            done, pending = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+            while done:
+                yield done.pop()
+    finally:
+        await cancel_futures(pending)

without_async-0.0.7/src/without_async/testing.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import asyncio
+
+
+async def yield_once() -> None:
+    """
+    Yield control for exactly one event-loop turn, so a just-scheduled task
+    reaches its first suspension point.
+
+    Use this *only* to let a task you just `create_task`-d run far enough to park
+    on its first `await`, and *only* when the code it parks in gives you nothing
+    to wait on: a library coroutine like `sleep_forever`, or `Sample.updated`
+    registering its waiter just before it suspends. Proving such a task *blocks*
+    (rather than completing) means giving it one turn and then observing it is
+    still pending; there is no signal to await instead, because the suspension
+    happens inside code you do not control. Cancelling before that turn would
+    preempt the task at its very first step, so the test would pass even for a
+    task that never blocks: the one turn is what makes the assertion meaningful.
+
+    It is one deterministic turn, not a timing guess. The scheduled task can only
+    park or finish within that turn, so a single `yield_once()` is exact; it never
+    needs a second call or a retry loop.
+
+    Avoid it everywhere a real signal exists, which is almost everywhere. If the
+    code you are waiting on is yours, have it announce its progress and wait on
+    that:
+
+    - waiting for a worker to reach a point: `set` an `asyncio.Event` (or
+      `release` a `Semaphore`) there and `await` it;
+    - waiting for a sampled `Context` to pick up the next value: `await
+      context.updated()`;
+    - waiting for a stream or queue to drain: drive it to completion and assert
+      on the result.
+
+    Reaching for `yield_once()` to "wait until the background work has probably
+    caught up" is the anti-pattern it must not become: yielding once and *hoping*
+    is a race, no matter how many times you call it. Use an explicit signal there.
+    """
+    await asyncio.sleep(0)
+
+
+async def resolved_next_turn[T](value: T) -> T:
+    """
+    Suspend for one event-loop turn, then return `value`.
+
+    A deterministic stand-in for awaited contained I/O (a DB read, an RPC) in a
+    test that needs a step or a unit of work to *genuinely* suspend and resume.
+    The future is resolved on the next turn via `call_soon`, which forces a real
+    suspension; awaiting an already-resolved future returns without ever yielding
+    control, so the "contained I/O suspends" path would go untested. Like
+    `yield_once`, it is one deterministic turn, not a timing guess.
+    """
+    loop = asyncio.get_running_loop()
+    result: asyncio.Future[T] = loop.create_future()
+
+    def resolve() -> None:
+        if not result.done():  # the awaiting task may have cancelled `result` before this turn
+            result.set_result(value)
+
+    loop.call_soon(resolve)
+    return await result

without_async-0.0.0/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.3
-Name: without-async
-Version: 0.0.0
-Summary: Placeholder reserving the PyPI project name; the first real release supersedes it.
-Requires-Python: >=3.9

without_async-0.0.0/pyproject.toml

@@ -1,9 +0,0 @@
-[build-system]
-requires = ["uv_build>=0.11,<0.12"]
-build-backend = "uv_build"
-
-[project]
-name = "without-async"
-version = "0.0.0"
-description = "Placeholder reserving the PyPI project name; the first real release supersedes it."
-requires-python = ">=3.9"

without_async-0.0.0/pyproject.toml.orig

@@ -1,9 +0,0 @@
-[build-system]
-requires = ["uv_build>=0.11,<0.12"]
-build-backend = "uv_build"
-
-[project]
-name = "without-async"
-version = "0.0.0"
-description = "Placeholder reserving the PyPI project name; the first real release supersedes it."
-requires-python = ">=3.9"