hojichar.utils.async_handlers

  1from __future__ import annotations
  2
  3import asyncio
  4import itertools
  5import logging
  6import queue
  7import threading
  8from collections.abc import AsyncGenerator, AsyncIterable, Awaitable, Callable, Iterable, Iterator
  9from concurrent.futures import ThreadPoolExecutor
 10from pathlib import Path
 11from typing import Any, Generic, TextIO, TypeVar, cast
 12
 13T = TypeVar("T")
 14logger = logging.getLogger(__name__)
 15
 16
 17class _AsyncIteratorError:
 18    def __init__(self, error: BaseException):
 19        self.error = error
 20
 21
 22_ASYNC_ITERATOR_END = object()
 23
 24
 25class AsyncToSyncIterator(Iterator[T], Generic[T]):
 26    """Consume an async iterable from synchronous code.
 27
 28    A single background thread owns the event loop for the lifetime of the iterator. Use
 29    this class as a context manager when iteration may stop before the source is exhausted.
 30    """
 31
 32    def __init__(
 33        self,
 34        source_stream: AsyncIterable[T],
 35        *,
 36        buffer_size: int = 128,
 37        finalizer: Callable[[], Awaitable[None]] | None = None,
 38    ) -> None:
 39        if buffer_size < 1:
 40            raise ValueError("buffer_size must be at least 1")
 41
 42        self._source_stream = source_stream
 43        self._queue: queue.Queue[Any] = queue.Queue(maxsize=buffer_size)
 44        self._finalizer = finalizer
 45        self._stop_event = threading.Event()
 46        self._started_event = threading.Event()
 47        self._thread: threading.Thread | None = None
 48        self._loop: asyncio.AbstractEventLoop | None = None
 49        self._consumer_task: asyncio.Task[None] | None = None
 50        self._closed = False
 51
 52    def __iter__(self) -> "AsyncToSyncIterator[T]":
 53        return self
 54
 55    def __next__(self) -> T:
 56        if self._closed:
 57            raise StopIteration
 58        self._start()
 59
 60        item = self._queue.get()
 61        if item is _ASYNC_ITERATOR_END:
 62            self.close()
 63            raise StopIteration
 64        if isinstance(item, _AsyncIteratorError):
 65            self.close()
 66            raise item.error
 67        return cast(T, item)
 68
 69    def __enter__(self) -> "AsyncToSyncIterator[T]":
 70        return self
 71
 72    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
 73        self.close()
 74
 75    def close(self) -> None:
 76        if self._closed:
 77            return
 78        self._closed = True
 79        self._stop_event.set()
 80        thread_was_started = self._thread is not None
 81
 82        if not thread_was_started:
 83            # Closing an unconsumed iterator must still close its source and run its finalizer.
 84            self._thread = threading.Thread(
 85                target=self._thread_main,
 86                name="hojichar-async-to-sync",
 87                daemon=True,
 88            )
 89            self._thread.start()
 90            self._started_event.wait()
 91
 92        while True:
 93            try:
 94                self._queue.get_nowait()
 95            except queue.Empty:
 96                break
 97
 98        if (
 99            thread_was_started
100            and self._thread is not None
101            and self._thread.is_alive()
102            and self._loop is not None
103            and not self._loop.is_closed()
104            and self._consumer_task is not None
105        ):
106            try:
107                self._loop.call_soon_threadsafe(self._consumer_task.cancel)
108            except RuntimeError:
109                # The background loop can close between is_closed() and scheduling.
110                pass
111
112        if self._thread is not None:
113            self._thread.join(timeout=5.0)
114            if self._thread.is_alive():
115                logger.warning("Async-to-sync iterator did not stop within 5 seconds")
116
117    def _start(self) -> None:
118        if self._thread is not None:
119            return
120        try:
121            asyncio.get_running_loop()
122        except RuntimeError:
123            pass
124        else:
125            raise RuntimeError(
126                "Cannot synchronously consume an async iterable from a running event loop"
127            )
128
129        self._thread = threading.Thread(
130            target=self._thread_main,
131            name="hojichar-async-to-sync",
132            daemon=True,
133        )
134        self._thread.start()
135        self._started_event.wait()
136
137    def _thread_main(self) -> None:
138        try:
139            asyncio.run(self._consume())
140        except BaseException as error:
141            if not self._stop_event.is_set():
142                self._put(_AsyncIteratorError(error))
143            elif not isinstance(error, asyncio.CancelledError):
144                logger.error("Failed to close async-to-sync iterator", exc_info=True)
145        finally:
146            self._started_event.set()
147            if not self._stop_event.is_set():
148                self._put(_ASYNC_ITERATOR_END)
149
150    async def _consume(self) -> None:
151        self._loop = asyncio.get_running_loop()
152        self._consumer_task = asyncio.current_task()
153        self._started_event.set()
154        iterator = None
155
156        try:
157            iterator = self._source_stream.__aiter__()
158            while not self._stop_event.is_set():
159                try:
160                    item = await iterator.__anext__()
161                except StopAsyncIteration:
162                    break
163                if not self._put(item):
164                    break
165        finally:
166            try:
167                aclose = getattr(iterator, "aclose", None)
168                if aclose is not None:
169                    await aclose()
170            finally:
171                if self._finalizer is not None:
172                    await self._finalizer()
173
174    def _put(self, item: Any) -> bool:
175        while not self._stop_event.is_set():
176            try:
177                self._queue.put(item, timeout=0.05)
178                return True
179            except queue.Full:
180                continue
181        return False
182
183
184def handle_stream_as_async(
185    source_stream: Iterable[T] | AsyncIterable[T],
186    chunk_size: int = 1000,
187    executor: ThreadPoolExecutor | None = None,
188) -> AsyncGenerator[T, None]:
189    """
190    Convert a synchronous iterable to an asynchronous generator
191    with a specified chunk size.
192
193    Args:
194        source_stream (Iterable[T]): The synchronous iterable to convert.
195        chunk_size (int): The number of items to yield at a time.
196    """
197    if isinstance(source_stream, AsyncIterable):
198        return source_stream  # type: ignore[return-value]
199    stream = iter(source_stream)
200
201    async def sync_to_async() -> AsyncGenerator[T, None]:
202        loop = asyncio.get_running_loop()
203        while True:
204            chunk = await loop.run_in_executor(
205                executor, lambda: list(itertools.islice(stream, chunk_size))
206            )
207            if not chunk:
208                break
209            for item in chunk:
210                yield item
211
212    return sync_to_async()
213
214
215def handle_async_stream_as_sync(
216    source_stream: AsyncIterable[T],
217    *,
218    buffer_size: int = 128,
219    finalizer: Callable[[], Awaitable[None]] | None = None,
220) -> AsyncToSyncIterator[T]:
221    """Convert an async iterable to a synchronous, closeable iterator.
222
223    The iterator owns a background event-loop thread. Fully consuming it closes the source
224    automatically. Use it as a context manager when the consumer may stop early.
225    """
226    return AsyncToSyncIterator(
227        source_stream,
228        buffer_size=buffer_size,
229        finalizer=finalizer,
230    )
231
232
233async def write_stream_to_file(
234    stream: AsyncGenerator[str, None],
235    output_path: Path | str,
236    *,
237    chunk_size: int = 1000,
238    delimiter: str = "\n",
239) -> None:
240    """
241    Write an asynchronous stream of strings to a file.
242    To lessen overhead with file I/O, it writes in chunks.
243    """
244    loop = asyncio.get_running_loop()
245    with open(output_path, "w", encoding="utf-8") as f:
246        chunk = []
247        async for line in stream:
248            chunk.append(line)
249            if len(chunk) >= chunk_size:
250                await loop.run_in_executor(None, f.writelines, [s + delimiter for s in chunk])
251                chunk = []
252        if chunk:
253            await loop.run_in_executor(None, f.writelines, [s + delimiter for s in chunk])
254            chunk = []
255        await loop.run_in_executor(None, f.flush)
256
257
258async def fileout_from_async_iter(
259    fp: TextIO, iter: AsyncIterable[str], buffer_size: int = 128
260) -> None:
261    buffer = []
262    async for line in iter:
263        buffer.append(line + "\n")
264        if len(buffer) >= buffer_size:
265            await asyncio.to_thread(fp.write, "".join(buffer))
266            buffer.clear()
267    await asyncio.to_thread(fp.writelines, buffer)
268    buffer.clear()
class AsyncToSyncIterator(collections.abc.Iterator[~T], typing.Generic[~T]):
 26class AsyncToSyncIterator(Iterator[T], Generic[T]):
 27    """Consume an async iterable from synchronous code.
 28
 29    A single background thread owns the event loop for the lifetime of the iterator. Use
 30    this class as a context manager when iteration may stop before the source is exhausted.
 31    """
 32
 33    def __init__(
 34        self,
 35        source_stream: AsyncIterable[T],
 36        *,
 37        buffer_size: int = 128,
 38        finalizer: Callable[[], Awaitable[None]] | None = None,
 39    ) -> None:
 40        if buffer_size < 1:
 41            raise ValueError("buffer_size must be at least 1")
 42
 43        self._source_stream = source_stream
 44        self._queue: queue.Queue[Any] = queue.Queue(maxsize=buffer_size)
 45        self._finalizer = finalizer
 46        self._stop_event = threading.Event()
 47        self._started_event = threading.Event()
 48        self._thread: threading.Thread | None = None
 49        self._loop: asyncio.AbstractEventLoop | None = None
 50        self._consumer_task: asyncio.Task[None] | None = None
 51        self._closed = False
 52
 53    def __iter__(self) -> "AsyncToSyncIterator[T]":
 54        return self
 55
 56    def __next__(self) -> T:
 57        if self._closed:
 58            raise StopIteration
 59        self._start()
 60
 61        item = self._queue.get()
 62        if item is _ASYNC_ITERATOR_END:
 63            self.close()
 64            raise StopIteration
 65        if isinstance(item, _AsyncIteratorError):
 66            self.close()
 67            raise item.error
 68        return cast(T, item)
 69
 70    def __enter__(self) -> "AsyncToSyncIterator[T]":
 71        return self
 72
 73    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
 74        self.close()
 75
 76    def close(self) -> None:
 77        if self._closed:
 78            return
 79        self._closed = True
 80        self._stop_event.set()
 81        thread_was_started = self._thread is not None
 82
 83        if not thread_was_started:
 84            # Closing an unconsumed iterator must still close its source and run its finalizer.
 85            self._thread = threading.Thread(
 86                target=self._thread_main,
 87                name="hojichar-async-to-sync",
 88                daemon=True,
 89            )
 90            self._thread.start()
 91            self._started_event.wait()
 92
 93        while True:
 94            try:
 95                self._queue.get_nowait()
 96            except queue.Empty:
 97                break
 98
 99        if (
100            thread_was_started
101            and self._thread is not None
102            and self._thread.is_alive()
103            and self._loop is not None
104            and not self._loop.is_closed()
105            and self._consumer_task is not None
106        ):
107            try:
108                self._loop.call_soon_threadsafe(self._consumer_task.cancel)
109            except RuntimeError:
110                # The background loop can close between is_closed() and scheduling.
111                pass
112
113        if self._thread is not None:
114            self._thread.join(timeout=5.0)
115            if self._thread.is_alive():
116                logger.warning("Async-to-sync iterator did not stop within 5 seconds")
117
118    def _start(self) -> None:
119        if self._thread is not None:
120            return
121        try:
122            asyncio.get_running_loop()
123        except RuntimeError:
124            pass
125        else:
126            raise RuntimeError(
127                "Cannot synchronously consume an async iterable from a running event loop"
128            )
129
130        self._thread = threading.Thread(
131            target=self._thread_main,
132            name="hojichar-async-to-sync",
133            daemon=True,
134        )
135        self._thread.start()
136        self._started_event.wait()
137
138    def _thread_main(self) -> None:
139        try:
140            asyncio.run(self._consume())
141        except BaseException as error:
142            if not self._stop_event.is_set():
143                self._put(_AsyncIteratorError(error))
144            elif not isinstance(error, asyncio.CancelledError):
145                logger.error("Failed to close async-to-sync iterator", exc_info=True)
146        finally:
147            self._started_event.set()
148            if not self._stop_event.is_set():
149                self._put(_ASYNC_ITERATOR_END)
150
151    async def _consume(self) -> None:
152        self._loop = asyncio.get_running_loop()
153        self._consumer_task = asyncio.current_task()
154        self._started_event.set()
155        iterator = None
156
157        try:
158            iterator = self._source_stream.__aiter__()
159            while not self._stop_event.is_set():
160                try:
161                    item = await iterator.__anext__()
162                except StopAsyncIteration:
163                    break
164                if not self._put(item):
165                    break
166        finally:
167            try:
168                aclose = getattr(iterator, "aclose", None)
169                if aclose is not None:
170                    await aclose()
171            finally:
172                if self._finalizer is not None:
173                    await self._finalizer()
174
175    def _put(self, item: Any) -> bool:
176        while not self._stop_event.is_set():
177            try:
178                self._queue.put(item, timeout=0.05)
179                return True
180            except queue.Full:
181                continue
182        return False

Consume an async iterable from synchronous code.

A single background thread owns the event loop for the lifetime of the iterator. Use this class as a context manager when iteration may stop before the source is exhausted.

AsyncToSyncIterator( source_stream: collections.abc.AsyncIterable[~T], *, buffer_size: int = 128, finalizer: collections.abc.Callable[[], collections.abc.Awaitable[None]] | None = None)
33    def __init__(
34        self,
35        source_stream: AsyncIterable[T],
36        *,
37        buffer_size: int = 128,
38        finalizer: Callable[[], Awaitable[None]] | None = None,
39    ) -> None:
40        if buffer_size < 1:
41            raise ValueError("buffer_size must be at least 1")
42
43        self._source_stream = source_stream
44        self._queue: queue.Queue[Any] = queue.Queue(maxsize=buffer_size)
45        self._finalizer = finalizer
46        self._stop_event = threading.Event()
47        self._started_event = threading.Event()
48        self._thread: threading.Thread | None = None
49        self._loop: asyncio.AbstractEventLoop | None = None
50        self._consumer_task: asyncio.Task[None] | None = None
51        self._closed = False
def close(self) -> None:
 76    def close(self) -> None:
 77        if self._closed:
 78            return
 79        self._closed = True
 80        self._stop_event.set()
 81        thread_was_started = self._thread is not None
 82
 83        if not thread_was_started:
 84            # Closing an unconsumed iterator must still close its source and run its finalizer.
 85            self._thread = threading.Thread(
 86                target=self._thread_main,
 87                name="hojichar-async-to-sync",
 88                daemon=True,
 89            )
 90            self._thread.start()
 91            self._started_event.wait()
 92
 93        while True:
 94            try:
 95                self._queue.get_nowait()
 96            except queue.Empty:
 97                break
 98
 99        if (
100            thread_was_started
101            and self._thread is not None
102            and self._thread.is_alive()
103            and self._loop is not None
104            and not self._loop.is_closed()
105            and self._consumer_task is not None
106        ):
107            try:
108                self._loop.call_soon_threadsafe(self._consumer_task.cancel)
109            except RuntimeError:
110                # The background loop can close between is_closed() and scheduling.
111                pass
112
113        if self._thread is not None:
114            self._thread.join(timeout=5.0)
115            if self._thread.is_alive():
116                logger.warning("Async-to-sync iterator did not stop within 5 seconds")
def handle_stream_as_async( source_stream: collections.abc.Iterable[~T] | collections.abc.AsyncIterable[~T], chunk_size: int = 1000, executor: concurrent.futures.thread.ThreadPoolExecutor | None = None) -> collections.abc.AsyncGenerator[~T, None]:
185def handle_stream_as_async(
186    source_stream: Iterable[T] | AsyncIterable[T],
187    chunk_size: int = 1000,
188    executor: ThreadPoolExecutor | None = None,
189) -> AsyncGenerator[T, None]:
190    """
191    Convert a synchronous iterable to an asynchronous generator
192    with a specified chunk size.
193
194    Args:
195        source_stream (Iterable[T]): The synchronous iterable to convert.
196        chunk_size (int): The number of items to yield at a time.
197    """
198    if isinstance(source_stream, AsyncIterable):
199        return source_stream  # type: ignore[return-value]
200    stream = iter(source_stream)
201
202    async def sync_to_async() -> AsyncGenerator[T, None]:
203        loop = asyncio.get_running_loop()
204        while True:
205            chunk = await loop.run_in_executor(
206                executor, lambda: list(itertools.islice(stream, chunk_size))
207            )
208            if not chunk:
209                break
210            for item in chunk:
211                yield item
212
213    return sync_to_async()

Convert a synchronous iterable to an asynchronous generator with a specified chunk size.

Args: source_stream (Iterable[T]): The synchronous iterable to convert. chunk_size (int): The number of items to yield at a time.

def handle_async_stream_as_sync( source_stream: collections.abc.AsyncIterable[~T], *, buffer_size: int = 128, finalizer: collections.abc.Callable[[], collections.abc.Awaitable[None]] | None = None) -> hojichar.utils.async_handlers.AsyncToSyncIterator[~T]:
216def handle_async_stream_as_sync(
217    source_stream: AsyncIterable[T],
218    *,
219    buffer_size: int = 128,
220    finalizer: Callable[[], Awaitable[None]] | None = None,
221) -> AsyncToSyncIterator[T]:
222    """Convert an async iterable to a synchronous, closeable iterator.
223
224    The iterator owns a background event-loop thread. Fully consuming it closes the source
225    automatically. Use it as a context manager when the consumer may stop early.
226    """
227    return AsyncToSyncIterator(
228        source_stream,
229        buffer_size=buffer_size,
230        finalizer=finalizer,
231    )

Convert an async iterable to a synchronous, closeable iterator.

The iterator owns a background event-loop thread. Fully consuming it closes the source automatically. Use it as a context manager when the consumer may stop early.

async def write_stream_to_file( stream: collections.abc.AsyncGenerator[str, None], output_path: pathlib.Path | str, *, chunk_size: int = 1000, delimiter: str = '\n') -> None:
234async def write_stream_to_file(
235    stream: AsyncGenerator[str, None],
236    output_path: Path | str,
237    *,
238    chunk_size: int = 1000,
239    delimiter: str = "\n",
240) -> None:
241    """
242    Write an asynchronous stream of strings to a file.
243    To lessen overhead with file I/O, it writes in chunks.
244    """
245    loop = asyncio.get_running_loop()
246    with open(output_path, "w", encoding="utf-8") as f:
247        chunk = []
248        async for line in stream:
249            chunk.append(line)
250            if len(chunk) >= chunk_size:
251                await loop.run_in_executor(None, f.writelines, [s + delimiter for s in chunk])
252                chunk = []
253        if chunk:
254            await loop.run_in_executor(None, f.writelines, [s + delimiter for s in chunk])
255            chunk = []
256        await loop.run_in_executor(None, f.flush)

Write an asynchronous stream of strings to a file. To lessen overhead with file I/O, it writes in chunks.

async def fileout_from_async_iter( fp: <class 'TextIO'>, iter: collections.abc.AsyncIterable[str], buffer_size: int = 128) -> None:
259async def fileout_from_async_iter(
260    fp: TextIO, iter: AsyncIterable[str], buffer_size: int = 128
261) -> None:
262    buffer = []
263    async for line in iter:
264        buffer.append(line + "\n")
265        if len(buffer) >= buffer_size:
266            await asyncio.to_thread(fp.write, "".join(buffer))
267            buffer.clear()
268    await asyncio.to_thread(fp.writelines, buffer)
269    buffer.clear()