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.
- devkitx-1.0.0.dist-info/METADATA +560 -0
- devkitx-1.0.0.dist-info/RECORD +22 -0
- devkitx-1.0.0.dist-info/WHEEL +4 -0
- devkitx-1.0.0.dist-info/entry_points.txt +2 -0
- devkitx-1.0.0.dist-info/licenses/LICENSE +0 -0
- devtools_py/__init__.py +62 -0
- devtools_py/__main__.py +457 -0
- devtools_py/async_utils.py +436 -0
- devtools_py/cli_utils.py +320 -0
- devtools_py/config_utils.py +557 -0
- devtools_py/data_utils.py +288 -0
- devtools_py/dev_utils.py +393 -0
- devtools_py/file_utils.py +211 -0
- devtools_py/http_utils.py +346 -0
- devtools_py/json_utils.py +244 -0
- devtools_py/log_utils.py +158 -0
- devtools_py/py.typed +0 -0
- devtools_py/security_utils.py +326 -0
- devtools_py/string_utils.py +489 -0
- devtools_py/system_utils.py +262 -0
- devtools_py/time_utils.py +433 -0
- devtools_py/validation_utils.py +388 -0
|
@@ -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)
|