asynkit 0.19.2__tar.gz → 0.20.0__tar.gz

{asynkit-0.19.2/src/asynkit.egg-info → asynkit-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asynkit
-Version: 0.19.2
+Version: 0.20.0
 Summary: A toolkit for Python coroutines
 Author-email: Kristján Valur Jónsson <sweskman@gmail.com>
 License: MIT
@@ -445,11 +445,26 @@ stop signal and return instead; in that case it has intentionally decided not to
 block after all, and `await_sync()` returns its result. If the code tries to
 access the event loop, e.g. by creating a `Task`, a `RuntimeError` will be raised.
 
-The `syncfunction()` decorator can be used to automatically wrap an async function
-so that it is executed using `await_sync()`:
+#### Entering and leaving async code from synchronous code
+
+Sometimes you want to write logic once as `async def` but call it from synchronous
+code — and along the way, have that coroutine step back out into blocking synchronous
+implementations. asynkit supports this round trip with two complementary decorator
+pairs:
+
+| Step | Function | Method |
+| --- | --- | --- |
+| **Enter** async from sync | `enterasync()` | `enterasyncmethod()` |
+| **Leave** back to blocking sync | `leavesync()` | `leavesyncmethod()` |
+
+**Entering async from sync** — `enterasync()` / `enterasyncmethod()` let a synchronous
+caller enter non-blocking async code. Write the logic once as `async def`; the
+decorator runs it via `await_sync()`. The coroutine must complete without suspending
+on real I/O — if it blocks, `SynchronousError` is raised. This replaces hybrid
+functions that sometimes return awaitables.
 
 ```pycon
->>> @asynkit.syncfunction
+>>> @asynkit.enterasync
 ... async def sync_function():
 ...     async def async_function():
 ...         return "look, no async!"
@@ -460,30 +475,82 @@ so that it is executed using `await_sync()`:
 >>>
 ```
 
-For methods, use `syncmethod()` when creating a class-body alias. It behaves
-like `syncfunction()` at runtime, but exposes descriptor typing so type checkers
-can distinguish bound and unbound method access:
+For methods, use `enterasyncmethod()` when creating a class-body alias. It behaves like
+`enterasync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
 
 ```python
 class Runner:
     async def arun(self, *, yield_every: int | None = None) -> None: ...
 
-    run = asynkit.syncmethod(arun)
+    run = asynkit.enterasyncmethod(arun)
 ```
 
-the `asyncfunction()` utility can be used when passing synchronous callbacks to async
-code, to make them async. This, along with `syncfunction()` and `await_sync()`,
-can be used to integrate synchronous code with async middleware:
+**Leaving async back to sync** — `leavesync()` / `leavesyncmethod()` let sync-driven
+async code call back into a **blocking sync** implementation before returning to the
+synchronous caller. A common case is monkeypatching an async API with a blocking
+variant — for example greenlet-backed I/O or a thread-blocking socket `recv()`
+standing in for an async read. The wrapper presents that sync code as `async def` so
+it fits the async call chain, but raises `SyncDriveRequiredError` if `await`ed on a
+normal event loop. That guard assures the patched function is only reachable while
+the coroutine is being sync-driven — not from regular asyncio scheduling.
+
+The middleware pattern below shows the full round trip: the synchronous client
+**enters** async middleware; the middleware **leaves** back into a sync callback:
 
 ```python
-@asynkit.syncfunction
+@asynkit.enterasync
 async def sync_client(sync_callback):
-    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    middleware = AsyncMiddleware(asynkit.leavesync(sync_callback))
     return await middleware.run()
 ```
 
-Using this pattern, one can write the middleware completely async, make it also work
-for synchronous code, while avoiding the hybrid function _antipattern._
+For methods, use `leavesyncmethod()` when creating a class-body alias. It behaves like
+`leavesync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
+
+```python
+class Client:
+    def blocking_read(self, sock) -> bytes:
+        return sock.recv(4096)  # blocking stand-in for an async read
+
+    ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    async def afetch(self, sock) -> bytes:
+        return await self.ablocking_read(sock)
+
+
+# OK: driven synchronously via await_sync / enterasync / enterasyncmethod
+asynkit.await_sync(Client().afetch(sock))
+
+# Raises SyncDriveRequiredError on a real event loop
+await Client().afetch(sock)
+```
+
+`enterasync()` and `enterasyncmethod()` establish the sync-drive context indirectly,
+because they call `await_sync()`, which uses `drive_async()`.
+
+#### `drive_async()` and sync-drive context
+
+`coro_drive()` is the low-level coroutine pump and may be implemented in C for
+performance. `drive_async()` is the Python entry point that wraps `coro_drive()` and
+establishes sync-drive context for the duration of the pump. Use `drive_async()`
+rather than `coro_drive()` alone when `leavesync()` or `require_sync_drive()`
+must work.
+
+Helpers such as `in_sync_drive()` and `require_sync_drive()`
+let custom wrappers participate in the same contract. All coroutine code that runs
+between yields executes inside this context, so `leavesync()` checks work
+whether the pump underneath is pure Python or the C extension.
+
+```python
+def my_callback(yielded):
+    asynkit.require_sync_drive()  # OK while drive_async() is active
+    ...
+
+
+asynkit.drive_async(coro, my_callback)
+```
 
 #### `aiter_sync()`
 

{asynkit-0.19.2 → asynkit-0.20.0}/README.md

@@ -417,11 +417,26 @@ stop signal and return instead; in that case it has intentionally decided not to
 block after all, and `await_sync()` returns its result. If the code tries to
 access the event loop, e.g. by creating a `Task`, a `RuntimeError` will be raised.
 
-The `syncfunction()` decorator can be used to automatically wrap an async function
-so that it is executed using `await_sync()`:
+#### Entering and leaving async code from synchronous code
+
+Sometimes you want to write logic once as `async def` but call it from synchronous
+code — and along the way, have that coroutine step back out into blocking synchronous
+implementations. asynkit supports this round trip with two complementary decorator
+pairs:
+
+| Step | Function | Method |
+| --- | --- | --- |
+| **Enter** async from sync | `enterasync()` | `enterasyncmethod()` |
+| **Leave** back to blocking sync | `leavesync()` | `leavesyncmethod()` |
+
+**Entering async from sync** — `enterasync()` / `enterasyncmethod()` let a synchronous
+caller enter non-blocking async code. Write the logic once as `async def`; the
+decorator runs it via `await_sync()`. The coroutine must complete without suspending
+on real I/O — if it blocks, `SynchronousError` is raised. This replaces hybrid
+functions that sometimes return awaitables.
 
 ```pycon
->>> @asynkit.syncfunction
+>>> @asynkit.enterasync
 ... async def sync_function():
 ...     async def async_function():
 ...         return "look, no async!"
@@ -432,30 +447,82 @@ so that it is executed using `await_sync()`:
 >>>
 ```
 
-For methods, use `syncmethod()` when creating a class-body alias. It behaves
-like `syncfunction()` at runtime, but exposes descriptor typing so type checkers
-can distinguish bound and unbound method access:
+For methods, use `enterasyncmethod()` when creating a class-body alias. It behaves like
+`enterasync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
 
 ```python
 class Runner:
     async def arun(self, *, yield_every: int | None = None) -> None: ...
 
-    run = asynkit.syncmethod(arun)
+    run = asynkit.enterasyncmethod(arun)
 ```
 
-the `asyncfunction()` utility can be used when passing synchronous callbacks to async
-code, to make them async. This, along with `syncfunction()` and `await_sync()`,
-can be used to integrate synchronous code with async middleware:
+**Leaving async back to sync** — `leavesync()` / `leavesyncmethod()` let sync-driven
+async code call back into a **blocking sync** implementation before returning to the
+synchronous caller. A common case is monkeypatching an async API with a blocking
+variant — for example greenlet-backed I/O or a thread-blocking socket `recv()`
+standing in for an async read. The wrapper presents that sync code as `async def` so
+it fits the async call chain, but raises `SyncDriveRequiredError` if `await`ed on a
+normal event loop. That guard assures the patched function is only reachable while
+the coroutine is being sync-driven — not from regular asyncio scheduling.
+
+The middleware pattern below shows the full round trip: the synchronous client
+**enters** async middleware; the middleware **leaves** back into a sync callback:
 
 ```python
-@asynkit.syncfunction
+@asynkit.enterasync
 async def sync_client(sync_callback):
-    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    middleware = AsyncMiddleware(asynkit.leavesync(sync_callback))
     return await middleware.run()
 ```
 
-Using this pattern, one can write the middleware completely async, make it also work
-for synchronous code, while avoiding the hybrid function _antipattern._
+For methods, use `leavesyncmethod()` when creating a class-body alias. It behaves like
+`leavesync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
+
+```python
+class Client:
+    def blocking_read(self, sock) -> bytes:
+        return sock.recv(4096)  # blocking stand-in for an async read
+
+    ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    async def afetch(self, sock) -> bytes:
+        return await self.ablocking_read(sock)
+
+
+# OK: driven synchronously via await_sync / enterasync / enterasyncmethod
+asynkit.await_sync(Client().afetch(sock))
+
+# Raises SyncDriveRequiredError on a real event loop
+await Client().afetch(sock)
+```
+
+`enterasync()` and `enterasyncmethod()` establish the sync-drive context indirectly,
+because they call `await_sync()`, which uses `drive_async()`.
+
+#### `drive_async()` and sync-drive context
+
+`coro_drive()` is the low-level coroutine pump and may be implemented in C for
+performance. `drive_async()` is the Python entry point that wraps `coro_drive()` and
+establishes sync-drive context for the duration of the pump. Use `drive_async()`
+rather than `coro_drive()` alone when `leavesync()` or `require_sync_drive()`
+must work.
+
+Helpers such as `in_sync_drive()` and `require_sync_drive()`
+let custom wrappers participate in the same contract. All coroutine code that runs
+between yields executes inside this context, so `leavesync()` checks work
+whether the pump underneath is pure Python or the C extension.
+
+```python
+def my_callback(yielded):
+    asynkit.require_sync_drive()  # OK while drive_async() is active
+    ...
+
+
+asynkit.drive_async(coro, my_callback)
+```
 
 #### `aiter_sync()`
 

{asynkit-0.19.2 → asynkit-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asynkit"
-version = "0.19.2"
+version = "0.20.0"
 description = "A toolkit for Python coroutines"
 authors = [
     {name = "Kristján Valur Jónsson", email = "sweskman@gmail.com"}

{asynkit-0.19.2 → asynkit-0.20.0}/src/asynkit/coroutine.py

@@ -6,6 +6,7 @@ import functools
 import importlib
 import inspect
 import sys
+import threading
 import types
 from asyncio import Future, Task
 from collections.abc import (
@@ -17,7 +18,7 @@ from collections.abc import (
     Generator,
     Iterator,
 )
-from contextvars import Context, copy_context
+from contextvars import Context, ContextVar, copy_context
 from types import FrameType
 from typing import (
     TYPE_CHECKING,
@@ -130,12 +131,18 @@ __all__ = [
     "coro_iter",
     "aiter_sync",
     "await_sync",
+    "drive_async",
+    "in_sync_drive",
+    "require_sync_drive",
     "SynchronousError",
     "SynchronousAbort",
-    "asyncfunction",
-    "syncfunction",
-    "syncmethod",
-    "SyncMethod",
+    "SyncDriveRequiredError",
+    "enterasync",
+    "enterasyncmethod",
+    "EnterAsyncMethod",
+    "leavesync",
+    "leavesyncmethod",
+    "LeaveSyncMethod",
 ]
 
 
@@ -187,6 +194,84 @@ class SynchronousAbort(BaseException):
     """
 
 
+class SyncDriveRequiredError(RuntimeError):
+    """Raised when a sync-drive-only async wrapper is awaited outside drive_async."""
+
+
+_sync_drive_session: ContextVar[int] = ContextVar("_sync_drive_session", default=0)
+_sync_drive_thread_state = threading.local()
+_session_id_lock = threading.Lock()
+_next_session_id = 0
+
+
+class _ThreadSyncDriveState:
+    __slots__ = ("lock", "active_sessions")
+
+    lock: threading.Lock
+    active_sessions: list[int]
+
+    def __init__(self) -> None:
+        self.lock = threading.Lock()
+        self.active_sessions = []
+
+
+def _allocate_sync_drive_session() -> int:
+    global _next_session_id
+
+    with _session_id_lock:
+        _next_session_id += 1
+        return _next_session_id
+
+
+def _thread_sync_drive_state() -> _ThreadSyncDriveState:
+    state = getattr(_sync_drive_thread_state, "state", None)
+    if state is None:
+        state = _ThreadSyncDriveState()
+        _sync_drive_thread_state.state = state
+    return state
+
+
+def _sync_drive_session_active() -> bool:
+    session = _sync_drive_session.get()
+    if session == 0:
+        return False
+    state = _thread_sync_drive_state()
+    with state.lock:
+        return session in state.active_sessions
+
+
+def in_sync_drive() -> bool:
+    """Return True when the current context is inside an active drive_async()."""
+    return _sync_drive_session_active()
+
+
+def require_sync_drive() -> None:
+    """Require that the current context is inside an active drive_async()."""
+    if not _sync_drive_session_active():
+        raise SyncDriveRequiredError(
+            "operation requires a coroutine being synchronously driven "
+            "(e.g. via await_sync())"
+        )
+
+
+@contextlib.contextmanager
+def _sync_drive_context() -> Generator[None, None, None]:
+    session = _allocate_sync_drive_session()
+    session_token = _sync_drive_session.set(session)
+    state = _thread_sync_drive_state()
+    with state.lock:
+        state.active_sessions.append(session)
+    try:
+        yield
+    finally:
+        try:
+            with state.lock:
+                if session in state.active_sessions:
+                    state.active_sessions.remove(session)
+        finally:
+            _sync_drive_session.reset(session_token)
+
+
 # Helpers to find if a coroutine (or a generator as created by types.coroutine)
 # has started or finished
 
@@ -1071,7 +1156,11 @@ def coro_iter(coro: Coroutine[Any, Any, T]) -> Generator[Any, Any, T]:
 
 
 def coro_drive(coro: Coroutine[Any, Any, T], callback: _CoroYieldCallback) -> T:
-    """Drive a coroutine by passing each yielded value to a callback."""
+    """Drive a coroutine by passing each yielded value to a callback.
+
+    This is the low-level pump. Use `drive_async()` instead when
+    `leavesync()` or `require_sync_drive()` must work.
+    """
     send_value = None
     pending_error: BaseException | None = None
 
@@ -1103,6 +1192,17 @@ if not TYPE_CHECKING and _HAVE_C_EXTENSION and _c_coro_drive is not None:
     coro_drive = _c_coro_drive
 
 
+def drive_async(coro: Coroutine[Any, Any, T], callback: _CoroYieldCallback) -> T:
+    """Drive a coroutine synchronously and mark the context as sync-driven.
+
+    Custom synchronous pumps must use this rather than `coro_drive()` alone
+    when participating in the sync-drive contract used by `leavesync()`
+    and `require_sync_drive()`. Session tracking is per-thread.
+    """
+    with _sync_drive_context():
+        return coro_drive(coro, callback)
+
+
 def awaitmethod(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Iterator[T]]:
     """
     Decorator to make a function return an awaitable.
@@ -1155,14 +1255,16 @@ def await_sync(coro: Coroutine[Any, Any, T], *, ignore_nullsleep: bool = True) -
         raise GeneratorExit()
 
     try:
-        return coro_drive(coro, callback)
+        return drive_async(coro, callback)
     except (GeneratorExit, SynchronousAbort) as err:
         raise SynchronousError("coroutine failed to complete synchronously") from err
 
 
-def syncfunction(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, T]:
-    """Make an async function synchronous, by invoking
-    `await_sync()` on its coroutine.  Useful as a decorator.
+def enterasync(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, T]:
+    """Let synchronous callers enter non-blocking async code.
+
+    Runs the coroutine via `await_sync()`. Pair with `leavesync()` when
+    sync-driven async code must leave back into blocking sync implementations.
     """
 
     @functools.wraps(func)
@@ -1172,11 +1274,11 @@ def syncfunction(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, T]:
     return helper
 
 
-class SyncMethod(Generic[SelfT, P, T]):
-    """Descriptor which makes an async method synchronous.
+class EnterAsyncMethod(Generic[SelfT, P, T]):
+    """Descriptor for entering non-blocking async methods from synchronous callers.
 
-    Unlike `syncfunction()`, this preserves method binding semantics when used
-    for class-body aliases such as `run = syncmethod(arun)`.
+    Unlike `enterasync()`, this preserves method binding semantics when used
+    for class-body aliases such as `run = enterasyncmethod(arun)`.
     """
 
     def __init__(
@@ -1218,25 +1320,92 @@ class SyncMethod(Generic[SelfT, P, T]):
         return await_sync(self._func(instance, *args, **kwargs))
 
 
-def syncmethod(
+def enterasyncmethod(
     func: Callable[Concatenate[SelfT, P], Coroutine[Any, Any, T]],
-) -> SyncMethod[SelfT, P, T]:
-    """Make an async method synchronous while preserving descriptor typing."""
-    return SyncMethod(func)
+) -> EnterAsyncMethod[SelfT, P, T]:
+    """Enter non-blocking async methods from synchronous callers.
+
+    Preserves descriptor typing for class-body aliases such as
+    `run = enterasyncmethod(arun)`.
+    """
+    return EnterAsyncMethod(func)
 
 
-def asyncfunction(func: Callable[P, T]) -> Callable[P, Coroutine[Any, Any, T]]:
-    """Make a regular function async, so that its result needs to be awaited.
-    Useful when providing synchronous callbacks to async code.
+def leavesync(func: Callable[P, T]) -> Callable[P, Coroutine[Any, Any, T]]:
+    """Let sync-driven async code leave back into blocking sync implementations.
+
+    Pair with `enterasync()`: after entering async from sync, a coroutine may
+    step out into blocking sync callbacks such as patched stand-ins for formerly-
+    async APIs. Raises `SyncDriveRequiredError` when awaited outside `drive_async()`.
     """
 
     @functools.wraps(func)
     async def helper(*args: P.args, **kwargs: P.kwargs) -> T:
+        require_sync_drive()
         return func(*args, **kwargs)
 
     return helper
 
 
+class LeaveSyncMethod(Generic[SelfT, P, T]):
+    """Descriptor for leaving sync-driven async code back into blocking sync methods.
+
+    Unlike `leavesync()`, this preserves method binding semantics when used
+    for class-body aliases such as `ablocking_read = leavesyncmethod(blocking_read)`.
+    """
+
+    def __init__(
+        self,
+        func: Callable[Concatenate[SelfT, P], T],
+    ) -> None:
+        self._func = func
+        functools.update_wrapper(self, func)
+
+    @overload
+    def __get__(
+        self,
+        instance: None,
+        owner: type[SelfT],
+    ) -> Callable[Concatenate[SelfT, P], Coroutine[Any, Any, T]]: ...
+
+    @overload
+    def __get__(
+        self,
+        instance: SelfT,
+        owner: type[SelfT] | None = None,
+    ) -> Callable[P, Coroutine[Any, Any, T]]: ...
+
+    def __get__(
+        self,
+        instance: SelfT | None,
+        owner: type[SelfT] | None = None,
+    ) -> Callable[..., Coroutine[Any, Any, T]]:
+        if instance is None:
+            return self
+
+        @functools.wraps(self._func)
+        async def helper(*args: P.args, **kwargs: P.kwargs) -> T:
+            require_sync_drive()
+            return self._func(instance, *args, **kwargs)
+
+        return helper
+
+    async def __call__(self, instance: SelfT, *args: P.args, **kwargs: P.kwargs) -> T:
+        require_sync_drive()
+        return self._func(instance, *args, **kwargs)
+
+
+def leavesyncmethod(
+    func: Callable[Concatenate[SelfT, P], T],
+) -> LeaveSyncMethod[SelfT, P, T]:
+    """Leave sync-driven async code back into blocking sync methods.
+
+    Preserves descriptor typing for class-body aliases such as
+    `ablocking_read = leavesyncmethod(blocking_read)`.
+    """
+    return LeaveSyncMethod(func)
+
+
 def aiter_sync(async_iterable: AsyncIterable[T]) -> Generator[T, None, None]:
     """Iterate synchronously over an async iterable"""
     ai = async_iterable.__aiter__()

{asynkit-0.19.2 → asynkit-0.20.0/src/asynkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asynkit
-Version: 0.19.2
+Version: 0.20.0
 Summary: A toolkit for Python coroutines
 Author-email: Kristján Valur Jónsson <sweskman@gmail.com>
 License: MIT
@@ -445,11 +445,26 @@ stop signal and return instead; in that case it has intentionally decided not to
 block after all, and `await_sync()` returns its result. If the code tries to
 access the event loop, e.g. by creating a `Task`, a `RuntimeError` will be raised.
 
-The `syncfunction()` decorator can be used to automatically wrap an async function
-so that it is executed using `await_sync()`:
+#### Entering and leaving async code from synchronous code
+
+Sometimes you want to write logic once as `async def` but call it from synchronous
+code — and along the way, have that coroutine step back out into blocking synchronous
+implementations. asynkit supports this round trip with two complementary decorator
+pairs:
+
+| Step | Function | Method |
+| --- | --- | --- |
+| **Enter** async from sync | `enterasync()` | `enterasyncmethod()` |
+| **Leave** back to blocking sync | `leavesync()` | `leavesyncmethod()` |
+
+**Entering async from sync** — `enterasync()` / `enterasyncmethod()` let a synchronous
+caller enter non-blocking async code. Write the logic once as `async def`; the
+decorator runs it via `await_sync()`. The coroutine must complete without suspending
+on real I/O — if it blocks, `SynchronousError` is raised. This replaces hybrid
+functions that sometimes return awaitables.
 
 ```pycon
->>> @asynkit.syncfunction
+>>> @asynkit.enterasync
 ... async def sync_function():
 ...     async def async_function():
 ...         return "look, no async!"
@@ -460,30 +475,82 @@ so that it is executed using `await_sync()`:
 >>>
 ```
 
-For methods, use `syncmethod()` when creating a class-body alias. It behaves
-like `syncfunction()` at runtime, but exposes descriptor typing so type checkers
-can distinguish bound and unbound method access:
+For methods, use `enterasyncmethod()` when creating a class-body alias. It behaves like
+`enterasync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
 
 ```python
 class Runner:
     async def arun(self, *, yield_every: int | None = None) -> None: ...
 
-    run = asynkit.syncmethod(arun)
+    run = asynkit.enterasyncmethod(arun)
 ```
 
-the `asyncfunction()` utility can be used when passing synchronous callbacks to async
-code, to make them async. This, along with `syncfunction()` and `await_sync()`,
-can be used to integrate synchronous code with async middleware:
+**Leaving async back to sync** — `leavesync()` / `leavesyncmethod()` let sync-driven
+async code call back into a **blocking sync** implementation before returning to the
+synchronous caller. A common case is monkeypatching an async API with a blocking
+variant — for example greenlet-backed I/O or a thread-blocking socket `recv()`
+standing in for an async read. The wrapper presents that sync code as `async def` so
+it fits the async call chain, but raises `SyncDriveRequiredError` if `await`ed on a
+normal event loop. That guard assures the patched function is only reachable while
+the coroutine is being sync-driven — not from regular asyncio scheduling.
+
+The middleware pattern below shows the full round trip: the synchronous client
+**enters** async middleware; the middleware **leaves** back into a sync callback:
 
 ```python
-@asynkit.syncfunction
+@asynkit.enterasync
 async def sync_client(sync_callback):
-    middleware = AsyncMiddleware(asynkit.asyncfunction(sync_callback))
+    middleware = AsyncMiddleware(asynkit.leavesync(sync_callback))
     return await middleware.run()
 ```
 
-Using this pattern, one can write the middleware completely async, make it also work
-for synchronous code, while avoiding the hybrid function _antipattern._
+For methods, use `leavesyncmethod()` when creating a class-body alias. It behaves like
+`leavesync()` at runtime, but exposes descriptor typing so type checkers can
+distinguish bound and unbound method access:
+
+```python
+class Client:
+    def blocking_read(self, sock) -> bytes:
+        return sock.recv(4096)  # blocking stand-in for an async read
+
+    ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    async def afetch(self, sock) -> bytes:
+        return await self.ablocking_read(sock)
+
+
+# OK: driven synchronously via await_sync / enterasync / enterasyncmethod
+asynkit.await_sync(Client().afetch(sock))
+
+# Raises SyncDriveRequiredError on a real event loop
+await Client().afetch(sock)
+```
+
+`enterasync()` and `enterasyncmethod()` establish the sync-drive context indirectly,
+because they call `await_sync()`, which uses `drive_async()`.
+
+#### `drive_async()` and sync-drive context
+
+`coro_drive()` is the low-level coroutine pump and may be implemented in C for
+performance. `drive_async()` is the Python entry point that wraps `coro_drive()` and
+establishes sync-drive context for the duration of the pump. Use `drive_async()`
+rather than `coro_drive()` alone when `leavesync()` or `require_sync_drive()`
+must work.
+
+Helpers such as `in_sync_drive()` and `require_sync_drive()`
+let custom wrappers participate in the same contract. All coroutine code that runs
+between yields executes inside this context, so `leavesync()` checks work
+whether the pump underneath is pure Python or the C extension.
+
+```python
+def my_callback(yielded):
+    asynkit.require_sync_drive()  # OK while drive_async() is active
+    ...
+
+
+asynkit.drive_async(coro, my_callback)
+```
 
 #### `aiter_sync()`
 

{asynkit-0.19.2 → asynkit-0.20.0}/tests/test_coro.py

@@ -829,20 +829,20 @@ class TestCoroRun:
     async def blocks(self):
         await drive_yield("blocked")
 
-    @asynkit.syncfunction
+    @asynkit.enterasync
     async def sync_simple(self):
         return await self.simple()
 
-    @asynkit.syncfunction
+    @asynkit.enterasync
     async def sync_cleanup(self):
         return await self.cleanupper()
 
-    @asynkit.syncfunction
+    @asynkit.enterasync
     async def sync_genexit(self):
         return await self.genexit()
 
-    method_simple = asynkit.syncmethod(simple)
-    method_blocks = asynkit.syncmethod(blocks)
+    method_simple = asynkit.enterasyncmethod(simple)
+    method_blocks = asynkit.enterasyncmethod(blocks)
 
     def test_simple(self):
         assert asynkit.await_sync(self.simple()) == "simple"
@@ -858,19 +858,19 @@ class TestCoroRun:
     def test_sync_simple(self):
         assert self.sync_simple() == "simple"
 
-    def test_syncmethod_bound(self):
+    def test_enterasyncmethod_bound(self):
         assert self.method_simple() == "simple"
 
-    def test_syncmethod_unbound(self):
+    def test_enterasyncmethod_unbound(self):
         assert type(self).method_simple(self) == "simple"
 
-    def test_syncmethod_descriptor(self):
+    def test_enterasyncmethod_descriptor(self):
         descriptor = type(self).__dict__["method_simple"]
-        assert isinstance(descriptor, asynkit.SyncMethod)
+        assert isinstance(descriptor, asynkit.EnterAsyncMethod)
         assert type(self).method_simple.__name__ == "simple"
         assert self.method_simple.__name__ == "simple"
 
-    def test_syncmethod_blocks(self):
+    def test_enterasyncmethod_blocks(self):
         with pytest.raises(asynkit.SynchronousError) as err:
             self.method_blocks()
         assert err.match("failed to complete synchronously")
@@ -1326,27 +1326,318 @@ class TestCoroIter:
             assert await a == "Awaiter5"
 
 
-async def test_async_function():
+def test_leavesync_inside_await_sync():
     def sync_method():
         return "foo"
 
-    @asynkit.asyncfunction
+    @asynkit.leavesync
     def sync_method2():
         return "bar"
 
-    assert await asynkit.asyncfunction(sync_method)() == "foo"
-    assert await sync_method2() == "bar"
+    async def wrapper() -> str:
+        return await asynkit.leavesync(sync_method)()
 
+    assert asynkit.await_sync(wrapper()) == "foo"
+    assert asynkit.await_sync(sync_method2()) == "bar"
 
-async def test_sync_function():
+
+async def test_leavesync_outside_sync_drive():
+    def sync_method():
+        return "foo"
+
+    @asynkit.leavesync
+    def sync_method2():
+        return "bar"
+
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        await asynkit.leavesync(sync_method)()
+    assert err.match("synchronously driven")
+
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        await sync_method2()
+    assert err.match("synchronously driven")
+
+
+async def test_leavesyncmethod_outside_sync_drive():
+    class Client:
+        def blocking_read(self) -> str:
+            return "payload"
+
+        ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    client = Client()
+
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        await client.ablocking_read()
+    assert err.match("synchronously driven")
+
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        await Client.ablocking_read(client)
+    assert err.match("synchronously driven")
+
+
+def test_leavesyncmethod_descriptor():
+    class Client:
+        def blocking_read(self) -> str:
+            return "payload"
+
+        ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    descriptor = Client.__dict__["ablocking_read"]
+    assert isinstance(descriptor, asynkit.LeaveSyncMethod)
+    assert Client.ablocking_read.__name__ == "blocking_read"
+    assert Client().ablocking_read.__name__ == "blocking_read"
+
+
+def test_leavesyncmethod_bound_inside_await_sync():
+    class Client:
+        def blocking_read(self) -> str:
+            return "payload"
+
+        ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    async def fetch() -> str:
+        return await Client().ablocking_read()
+
+    assert asynkit.await_sync(fetch()) == "payload"
+
+
+def test_leavesyncmethod_unbound_inside_await_sync():
+    class Client:
+        def blocking_read(self) -> str:
+            return "payload"
+
+        ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+    async def fetch(client: Client) -> str:
+        return await Client.ablocking_read(client)
+
+    assert asynkit.await_sync(fetch(Client())) == "payload"
+
+
+def test_sync_drive_context_cleared_after_await_sync_raises():
+    async def fails() -> None:
+        raise ValueError("boom")
+
+    with pytest.raises(ValueError, match="boom"):
+        asynkit.await_sync(fails())
+
+    assert not asynkit.in_sync_drive()
+    with pytest.raises(asynkit.SyncDriveRequiredError):
+        asynkit.require_sync_drive()
+
+
+def test_sync_drive_context_cleared_after_drive_async_raises():
+    async def coro() -> str:
+        await drive_yield(None)
+        return "done"
+
+    def callback(_yielded: object) -> None:
+        raise ValueError("callback boom")
+
+    with pytest.raises(ValueError, match="callback boom"):
+        asynkit.drive_async(coro(), callback)
+
+    assert not asynkit.in_sync_drive()
+    with pytest.raises(asynkit.SyncDriveRequiredError):
+        asynkit.require_sync_drive()
+
+
+def test_sync_drive_context_outside_drive():
+    assert not asynkit.in_sync_drive()
+
+
+def test_require_sync_drive_outside_drive():
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        asynkit.require_sync_drive()
+    assert err.match("synchronously driven")
+
+
+@pytest.mark.parametrize("_name,drive", coro_drive_implementations())
+def test_drive_async_sets_sync_drive_context(_name, drive, monkeypatch):
+    monkeypatch.setattr(asynkit.coroutine, "coro_drive", drive)
+    observations: dict[str, bool | None] = {
+        "callback": None,
+        "coro": None,
+    }
+
+    async def coro() -> str:
+        observations["coro"] = asynkit.in_sync_drive()
+        await drive_yield(None)
+        return "done"
+
+    def callback(yielded: object) -> None:
+        assert yielded is None
+        observations["callback"] = asynkit.in_sync_drive()
+        asynkit.require_sync_drive()
+
+    assert asynkit.drive_async(coro(), callback) == "done"
+    assert observations["callback"] is True
+    assert observations["coro"] is True
+
+
+@pytest.mark.parametrize("_name,drive", coro_drive_implementations())
+def test_coro_drive_does_not_set_sync_drive_context(_name, drive):
+    async def coro() -> str:
+        asynkit.require_sync_drive()
+        return "done"
+
+    with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+        drive(coro(), lambda _yielded: None)
+    assert err.match("synchronously driven")
+
+
+def test_copied_sync_drive_context_rejected_after_drive_ends():
+    captured: list[Any] = []
+
+    async def coro() -> str:
+        captured.append(copy_context())
+        return "done"
+
+    asynkit.drive_async(coro(), lambda _yielded: None)
+
+    with pytest.raises(asynkit.SyncDriveRequiredError):
+        captured[0].run(asynkit.require_sync_drive)
+
+
+def test_sync_drive_context_inside_await_sync():
+    async def record_context() -> None:
+        assert asynkit.in_sync_drive()
+
+    asynkit.await_sync(record_context())
+    assert not asynkit.in_sync_drive()
+
+
+def test_sync_drive_context_nested():
+    flags: list[bool] = []
+
+    async def inner() -> None:
+        flags.append(asynkit.in_sync_drive())
+
+    async def outer() -> None:
+        flags.append(asynkit.in_sync_drive())
+        asynkit.await_sync(inner())
+
+    asynkit.await_sync(outer())
+    assert flags == [True, True]
+    assert not asynkit.in_sync_drive()
+
+
+def test_enterasync_uses_drive_async_via_await_sync():
+    @asynkit.leavesync
+    def blocking_read() -> str:
+        return "payload"
+
+    @asynkit.enterasync
+    async def fetch() -> str:
+        return await blocking_read()
+
+    assert fetch() == "payload"
+
+
+def test_enterasyncmethod_uses_drive_async_via_await_sync():
+    class Client:
+        def blocking_read(self) -> str:
+            return "payload"
+
+        ablocking_read = asynkit.leavesyncmethod(blocking_read)
+
+        async def afetch(self) -> str:
+            return await self.ablocking_read()
+
+        fetch = asynkit.enterasyncmethod(afetch)
+
+    assert Client().fetch() == "payload"
+
+
+def test_copied_sync_drive_context_rejected_on_other_thread_during_drive():
+    import threading
+
+    a_context: list[Any] = []
+    result: list[str] = []
+
+    async def on_b() -> None:
+        async def on_a_capture() -> None:
+            a_context.append(copy_context())
+
+        thread_a = threading.Thread(target=lambda: asynkit.await_sync(on_a_capture()))
+        thread_a.start()
+        thread_a.join()
+
+        def probe() -> None:
+            try:
+                a_context[0].run(asynkit.require_sync_drive)
+                result.append("passed")
+            except asynkit.SyncDriveRequiredError:
+                result.append("rejected")
+
+        probe()
+
+    thread_b = threading.Thread(target=lambda: asynkit.await_sync(on_b()))
+    thread_b.start()
+    thread_b.join()
+    assert result == ["rejected"]
+
+
+def test_concurrent_drive_async_isolated_per_thread():
+    import threading
+
+    observations: list[tuple[str, bool]] = []
+    lock = threading.Lock()
+    start = threading.Barrier(2)
+
+    async def work(label: str) -> None:
+        start.wait(timeout=5)
+        with lock:
+            observations.append((label, asynkit.in_sync_drive()))
+
+    def run(label: str) -> None:
+        asynkit.await_sync(work(label))
+
+    threads = [threading.Thread(target=run, args=(label,)) for label in ("a", "b")]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+
+    assert sorted(observations) == [("a", True), ("b", True)]
+
+
+class TestSyncDriveStaleContext:
+    @pytest.fixture
+    def anyio_backend(self):
+        return "asyncio"
+
+    async def test_leavesync_rejects_stale_copied_context(self):
+        ran: list[bool] = []
+
+        @asynkit.leavesync
+        def blocking_read() -> str:
+            ran.append(True)
+            return "payload"
+
+        async def deferred() -> str:
+            return await blocking_read()
+
+        async def coro_with_task():
+            return asyncio.create_task(deferred())
+
+        task = asynkit.await_sync(coro_with_task())
+        with pytest.raises(asynkit.SyncDriveRequiredError) as err:
+            await task
+        assert err.match("synchronously driven")
+        assert ran == []
+
+
+def test_enterasync_function():
     async def async_method():
         return "foo"
 
-    @asynkit.syncfunction
+    @asynkit.enterasync
     async def async_method2():
         return "bar"
 
-    assert asynkit.syncfunction(async_method)() == "foo"
+    assert asynkit.enterasync(async_method)() == "foo"
     assert async_method2() == "bar"
 
 

{asynkit-0.19.2 → asynkit-0.20.0}/tests/test_namespace.py

@@ -20,8 +20,16 @@ def test_package_star_exports_public_api_only():
     assert exports == set(asynkit.__all__)
     assert "coro_start" in exports
     assert "coro_drive" in exports
-    assert "syncmethod" in exports
-    assert "SyncMethod" in exports
+    assert "enterasync" in exports
+    assert "enterasyncmethod" in exports
+    assert "EnterAsyncMethod" in exports
+    assert "leavesync" in exports
+    assert "leavesyncmethod" in exports
+    assert "LeaveSyncMethod" in exports
+    assert "drive_async" in exports
+    assert "in_sync_drive" in exports
+    assert "require_sync_drive" in exports
+    assert "SyncDriveRequiredError" in exports
     assert "cancelling" in exports
     assert "coroutine" not in exports
     assert "loop" not in exports