devkitx 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,436 @@
1
+ """Async-compatible utilities for DevKitX.
2
+
3
+ This module provides utilities for bridging sync/async code and
4
+ async-compatible versions of common operations.
5
+ """
6
+
7
+ import asyncio
8
+ import functools
9
+ import shutil
10
+ from concurrent.futures import ThreadPoolExecutor
11
+ from pathlib import Path
12
+ from typing import Any, Awaitable, Callable, TypeVar
13
+
14
+ T = TypeVar("T")
15
+
16
+ __all__ = [
17
+ "sync_to_async",
18
+ "async_to_sync",
19
+ "gather_with_limit",
20
+ "retry_async",
21
+ "AsyncFileManager",
22
+ ]
23
+
24
+
25
+ def sync_to_async(func: Callable[..., T]) -> Callable[..., Awaitable[T]]:
26
+ """Convert synchronous function to async.
27
+
28
+ This function wraps a synchronous function to run in a thread pool,
29
+ making it awaitable without blocking the event loop.
30
+
31
+ Args:
32
+ func: Synchronous function to convert
33
+
34
+ Returns:
35
+ Async version of the function
36
+
37
+ Example:
38
+ >>> def slow_sync_function(x: int) -> int:
39
+ ... time.sleep(1)
40
+ ... return x * 2
41
+ >>> async_func = sync_to_async(slow_sync_function)
42
+ >>> result = await async_func(5) # Returns 10 without blocking
43
+ """
44
+
45
+ @functools.wraps(func)
46
+ async def async_wrapper(*args: Any, **kwargs: Any) -> T:
47
+ loop = asyncio.get_event_loop()
48
+ with ThreadPoolExecutor() as executor:
49
+ return await loop.run_in_executor(executor, functools.partial(func, *args, **kwargs))
50
+
51
+ return async_wrapper
52
+
53
+
54
+ def async_to_sync(func: Callable[..., Awaitable[T]]) -> Callable[..., T]:
55
+ """Convert asynchronous function to sync.
56
+
57
+ This function wraps an async function to run synchronously by
58
+ creating or using an existing event loop.
59
+
60
+ Args:
61
+ func: Asynchronous function to convert
62
+
63
+ Returns:
64
+ Sync version of the function
65
+
66
+ Example:
67
+ >>> async def async_function(x: int) -> int:
68
+ ... await asyncio.sleep(0.1)
69
+ ... return x * 2
70
+ >>> sync_func = async_to_sync(async_function)
71
+ >>> result = sync_func(5) # Returns 10, blocks until complete
72
+ """
73
+
74
+ @functools.wraps(func)
75
+ def sync_wrapper(*args: Any, **kwargs: Any) -> T:
76
+ try:
77
+ # Try to get the current event loop
78
+ asyncio.get_running_loop()
79
+ # If we're already in an async context, we can't use asyncio.run()
80
+ # Instead, we need to schedule the coroutine
81
+ import concurrent.futures
82
+
83
+ with concurrent.futures.ThreadPoolExecutor() as executor:
84
+ future = executor.submit(asyncio.run, func(*args, **kwargs))
85
+ return future.result()
86
+ except RuntimeError:
87
+ # No event loop running, we can use asyncio.run()
88
+ return asyncio.run(func(*args, **kwargs))
89
+
90
+ return sync_wrapper
91
+
92
+
93
+ async def gather_with_limit(limit: int, *awaitables: Awaitable[T]) -> list[T]:
94
+ """Gather awaitables with concurrency limit.
95
+
96
+ Executes multiple awaitable objects concurrently but limits the number
97
+ of concurrent operations to prevent overwhelming the system.
98
+
99
+ Args:
100
+ limit: Maximum number of concurrent operations
101
+ *awaitables: Awaitable objects to gather
102
+
103
+ Returns:
104
+ List of results in the same order as input awaitables
105
+
106
+ Raises:
107
+ ValueError: If limit is less than 1
108
+
109
+ Example:
110
+ >>> async def fetch_data(url: str) -> str:
111
+ ... # Simulate API call
112
+ ... await asyncio.sleep(0.1)
113
+ ... return f"Data from {url}"
114
+ >>>
115
+ >>> urls = [f"http://api.example.com/{i}" for i in range(10)]
116
+ >>> tasks = [fetch_data(url) for url in urls]
117
+ >>> results = await gather_with_limit(3, *tasks) # Max 3 concurrent
118
+ """
119
+ if limit < 1:
120
+ raise ValueError("Limit must be at least 1")
121
+
122
+ if not awaitables:
123
+ return []
124
+
125
+ # Use asyncio.Semaphore to limit concurrency
126
+ semaphore = asyncio.Semaphore(limit)
127
+
128
+ async def _limited_awaitable(awaitable: Awaitable[T]) -> T:
129
+ async with semaphore:
130
+ return await awaitable
131
+
132
+ # Wrap all awaitables with semaphore
133
+ limited_awaitables = [_limited_awaitable(awaitable) for awaitable in awaitables]
134
+
135
+ # Gather all results
136
+ return await asyncio.gather(*limited_awaitables)
137
+
138
+
139
+ async def retry_async(
140
+ func: Callable[..., Awaitable[T]],
141
+ retries: int = 3,
142
+ delay: float = 1.0,
143
+ backoff_factor: float = 2.0,
144
+ exceptions: tuple[type[Exception], ...] = (Exception,),
145
+ *args: Any,
146
+ **kwargs: Any,
147
+ ) -> T:
148
+ """Retry async function with exponential backoff.
149
+
150
+ Attempts to execute an async function multiple times with increasing
151
+ delays between attempts if it fails.
152
+
153
+ Args:
154
+ func: Async function to retry
155
+ retries: Number of retry attempts (not including initial attempt)
156
+ delay: Initial delay between retries in seconds
157
+ backoff_factor: Multiplier for delay after each failed attempt
158
+ exceptions: Tuple of exception types to catch and retry on
159
+ *args: Arguments to pass to the function
160
+ **kwargs: Keyword arguments to pass to the function
161
+
162
+ Returns:
163
+ Function result
164
+
165
+ Raises:
166
+ The last exception raised by the function if all retries are exhausted
167
+
168
+ Example:
169
+ >>> async def unreliable_api_call(data: str) -> str:
170
+ ... if random.random() < 0.7: # 70% chance of failure
171
+ ... raise ConnectionError("API temporarily unavailable")
172
+ ... return f"Success: {data}"
173
+ >>>
174
+ >>> result = await retry_async(
175
+ ... unreliable_api_call,
176
+ ... retries=3,
177
+ ... delay=0.5,
178
+ ... exceptions=(ConnectionError,),
179
+ ... "test_data"
180
+ ... )
181
+ """
182
+ last_exception = None
183
+ current_delay = delay
184
+
185
+ for attempt in range(retries + 1): # +1 for initial attempt
186
+ try:
187
+ return await func(*args, **kwargs)
188
+ except exceptions as e:
189
+ last_exception = e
190
+ if attempt == retries: # Last attempt failed
191
+ break
192
+
193
+ # Wait before retrying
194
+ await asyncio.sleep(current_delay)
195
+ current_delay *= backoff_factor
196
+
197
+ # All attempts failed, raise the last exception
198
+ if last_exception:
199
+ raise last_exception
200
+ else:
201
+ # This shouldn't happen, but just in case
202
+ raise RuntimeError("All retry attempts failed")
203
+
204
+
205
+ class AsyncFileManager:
206
+ """Async file operations manager.
207
+
208
+ Provides async versions of common file operations that don't block
209
+ the event loop by running in a thread pool.
210
+
211
+ Example:
212
+ >>> async_fm = AsyncFileManager()
213
+ >>> content = await async_fm.read_text("example.txt")
214
+ >>> await async_fm.write_text("output.txt", "Hello, World!")
215
+ >>> await async_fm.copy_file("source.txt", "destination.txt")
216
+ """
217
+
218
+ def __init__(self, encoding: str = "utf-8"):
219
+ """Initialize AsyncFileManager.
220
+
221
+ Args:
222
+ encoding: Default text encoding for file operations
223
+ """
224
+ self.encoding = encoding
225
+
226
+ async def read_text(self, path: str | Path, encoding: str | None = None) -> str:
227
+ """Read text file asynchronously.
228
+
229
+ Args:
230
+ path: Path to file
231
+ encoding: Text encoding (defaults to instance encoding)
232
+
233
+ Returns:
234
+ File contents as string
235
+
236
+ Raises:
237
+ FileNotFoundError: If the file doesn't exist
238
+ PermissionError: If lacking read permissions
239
+ UnicodeDecodeError: If file can't be decoded with specified encoding
240
+ """
241
+ path_obj = Path(path)
242
+ encoding = encoding or self.encoding
243
+
244
+ def _read_sync() -> str:
245
+ return path_obj.read_text(encoding=encoding)
246
+
247
+ loop = asyncio.get_event_loop()
248
+ with ThreadPoolExecutor() as executor:
249
+ return await loop.run_in_executor(executor, _read_sync)
250
+
251
+ async def write_text(
252
+ self,
253
+ path: str | Path,
254
+ content: str,
255
+ encoding: str | None = None,
256
+ create_parents: bool = True,
257
+ ) -> None:
258
+ """Write text file asynchronously.
259
+
260
+ Args:
261
+ path: Path to file
262
+ content: Content to write
263
+ encoding: Text encoding (defaults to instance encoding)
264
+ create_parents: Whether to create parent directories if they don't exist
265
+
266
+ Raises:
267
+ PermissionError: If lacking write permissions
268
+ OSError: If unable to create parent directories
269
+ """
270
+ path_obj = Path(path)
271
+ encoding = encoding or self.encoding
272
+
273
+ def _write_sync() -> None:
274
+ if create_parents:
275
+ path_obj.parent.mkdir(parents=True, exist_ok=True)
276
+ path_obj.write_text(content, encoding=encoding)
277
+
278
+ loop = asyncio.get_event_loop()
279
+ with ThreadPoolExecutor() as executor:
280
+ await loop.run_in_executor(executor, _write_sync)
281
+
282
+ async def copy_file(
283
+ self, src: str | Path, dst: str | Path, create_parents: bool = True
284
+ ) -> None:
285
+ """Copy file asynchronously.
286
+
287
+ Args:
288
+ src: Source file path
289
+ dst: Destination file path
290
+ create_parents: Whether to create parent directories if they don't exist
291
+
292
+ Raises:
293
+ FileNotFoundError: If source file doesn't exist
294
+ PermissionError: If lacking read/write permissions
295
+ OSError: If unable to create parent directories
296
+ """
297
+ src_path = Path(src)
298
+ dst_path = Path(dst)
299
+
300
+ def _copy_sync() -> None:
301
+ if create_parents:
302
+ dst_path.parent.mkdir(parents=True, exist_ok=True)
303
+ shutil.copy2(src_path, dst_path)
304
+
305
+ loop = asyncio.get_event_loop()
306
+ with ThreadPoolExecutor() as executor:
307
+ await loop.run_in_executor(executor, _copy_sync)
308
+
309
+ async def read_bytes(self, path: str | Path) -> bytes:
310
+ """Read binary file asynchronously.
311
+
312
+ Args:
313
+ path: Path to file
314
+
315
+ Returns:
316
+ File contents as bytes
317
+
318
+ Raises:
319
+ FileNotFoundError: If the file doesn't exist
320
+ PermissionError: If lacking read permissions
321
+ """
322
+ path_obj = Path(path)
323
+
324
+ def _read_sync() -> bytes:
325
+ return path_obj.read_bytes()
326
+
327
+ loop = asyncio.get_event_loop()
328
+ with ThreadPoolExecutor() as executor:
329
+ return await loop.run_in_executor(executor, _read_sync)
330
+
331
+ async def write_bytes(
332
+ self, path: str | Path, content: bytes, create_parents: bool = True
333
+ ) -> None:
334
+ """Write binary file asynchronously.
335
+
336
+ Args:
337
+ path: Path to file
338
+ content: Content to write as bytes
339
+ create_parents: Whether to create parent directories if they don't exist
340
+
341
+ Raises:
342
+ PermissionError: If lacking write permissions
343
+ OSError: If unable to create parent directories
344
+ """
345
+ path_obj = Path(path)
346
+
347
+ def _write_sync() -> None:
348
+ if create_parents:
349
+ path_obj.parent.mkdir(parents=True, exist_ok=True)
350
+ path_obj.write_bytes(content)
351
+
352
+ loop = asyncio.get_event_loop()
353
+ with ThreadPoolExecutor() as executor:
354
+ await loop.run_in_executor(executor, _write_sync)
355
+
356
+ async def exists(self, path: str | Path) -> bool:
357
+ """Check if file exists asynchronously.
358
+
359
+ Args:
360
+ path: Path to check
361
+
362
+ Returns:
363
+ True if file exists, False otherwise
364
+ """
365
+ path_obj = Path(path)
366
+
367
+ def _exists_sync() -> bool:
368
+ return path_obj.exists()
369
+
370
+ loop = asyncio.get_event_loop()
371
+ with ThreadPoolExecutor() as executor:
372
+ return await loop.run_in_executor(executor, _exists_sync)
373
+
374
+ async def mkdir(self, path: str | Path, parents: bool = True, exist_ok: bool = True) -> None:
375
+ """Create directory asynchronously.
376
+
377
+ Args:
378
+ path: Directory path to create
379
+ parents: Whether to create parent directories
380
+ exist_ok: Whether to ignore if directory already exists
381
+
382
+ Raises:
383
+ FileExistsError: If directory exists and exist_ok is False
384
+ PermissionError: If lacking permissions to create directory
385
+ """
386
+ path_obj = Path(path)
387
+
388
+ def _mkdir_sync() -> None:
389
+ path_obj.mkdir(parents=parents, exist_ok=exist_ok)
390
+
391
+ loop = asyncio.get_event_loop()
392
+ with ThreadPoolExecutor() as executor:
393
+ await loop.run_in_executor(executor, _mkdir_sync)
394
+
395
+ async def remove(self, path: str | Path) -> None:
396
+ """Remove file asynchronously.
397
+
398
+ Args:
399
+ path: Path to file to remove
400
+
401
+ Raises:
402
+ FileNotFoundError: If file doesn't exist
403
+ PermissionError: If lacking permissions to remove file
404
+ IsADirectoryError: If path is a directory
405
+ """
406
+ path_obj = Path(path)
407
+
408
+ def _remove_sync() -> None:
409
+ path_obj.unlink()
410
+
411
+ loop = asyncio.get_event_loop()
412
+ with ThreadPoolExecutor() as executor:
413
+ await loop.run_in_executor(executor, _remove_sync)
414
+
415
+ async def list_dir(self, path: str | Path) -> list[Path]:
416
+ """List directory contents asynchronously.
417
+
418
+ Args:
419
+ path: Directory path to list
420
+
421
+ Returns:
422
+ List of Path objects for directory contents
423
+
424
+ Raises:
425
+ FileNotFoundError: If directory doesn't exist
426
+ NotADirectoryError: If path is not a directory
427
+ PermissionError: If lacking permissions to read directory
428
+ """
429
+ path_obj = Path(path)
430
+
431
+ def _list_sync() -> list[Path]:
432
+ return list(path_obj.iterdir())
433
+
434
+ loop = asyncio.get_event_loop()
435
+ with ThreadPoolExecutor() as executor:
436
+ return await loop.run_in_executor(executor, _list_sync)