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()
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.
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
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")
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.
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.
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.
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()