azrvus-dev-toolkit 0.1.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.
- azrvus_dev_toolkit-0.1.0.dist-info/METADATA +113 -0
- azrvus_dev_toolkit-0.1.0.dist-info/RECORD +45 -0
- azrvus_dev_toolkit-0.1.0.dist-info/WHEEL +4 -0
- azrvus_dev_toolkit-0.1.0.dist-info/entry_points.txt +2 -0
- azrvus_dev_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
- dev_toolkit/__init__.py +163 -0
- dev_toolkit/_version.py +3 -0
- dev_toolkit/async_io.py +19 -0
- dev_toolkit/banner.py +37 -0
- dev_toolkit/cache.py +88 -0
- dev_toolkit/cli.py +60 -0
- dev_toolkit/cli_formatters.py +79 -0
- dev_toolkit/cli_spinner.py +87 -0
- dev_toolkit/color.py +34 -0
- dev_toolkit/concurrency.py +58 -0
- dev_toolkit/config.py +75 -0
- dev_toolkit/crypto_utils.py +21 -0
- dev_toolkit/decorators.py +47 -0
- dev_toolkit/dict_utils.py +77 -0
- dev_toolkit/encoding.py +19 -0
- dev_toolkit/env.py +23 -0
- dev_toolkit/env_validator.py +24 -0
- dev_toolkit/events.py +44 -0
- dev_toolkit/formatters.py +45 -0
- dev_toolkit/hash.py +37 -0
- dev_toolkit/http.py +22 -0
- dev_toolkit/io.py +40 -0
- dev_toolkit/jsonl.py +62 -0
- dev_toolkit/logger.py +36 -0
- dev_toolkit/masking.py +51 -0
- dev_toolkit/pagination.py +29 -0
- dev_toolkit/path_utils.py +84 -0
- dev_toolkit/process.py +65 -0
- dev_toolkit/random_utils.py +19 -0
- dev_toolkit/rate_limiter.py +77 -0
- dev_toolkit/retry.py +37 -0
- dev_toolkit/retry_utils.py +93 -0
- dev_toolkit/system.py +24 -0
- dev_toolkit/templating.py +28 -0
- dev_toolkit/text.py +45 -0
- dev_toolkit/timer.py +41 -0
- dev_toolkit/transforms.py +21 -0
- dev_toolkit/url_utils.py +35 -0
- dev_toolkit/validators.py +74 -0
- dev_toolkit/watcher.py +66 -0
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import itertools
|
|
4
|
+
import sys
|
|
5
|
+
import threading
|
|
6
|
+
import time
|
|
7
|
+
from typing import TYPE_CHECKING, Any, Self
|
|
8
|
+
|
|
9
|
+
if TYPE_CHECKING:
|
|
10
|
+
from types import TracebackType
|
|
11
|
+
|
|
12
|
+
__all__ = ["Spinner"]
|
|
13
|
+
|
|
14
|
+
_SPINNER_STYLES: dict[str, list[str]] = {
|
|
15
|
+
"dots": ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
|
|
16
|
+
"line": ["-|", "\\", "|", "/"],
|
|
17
|
+
"block": ["█", "▓", "▒", "░"],
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Spinner:
|
|
22
|
+
"""A thread-safe terminal loading spinner context manager."""
|
|
23
|
+
|
|
24
|
+
def __init__(
|
|
25
|
+
self,
|
|
26
|
+
text: str = "Loading...",
|
|
27
|
+
style: str = "dots",
|
|
28
|
+
delay: float = 0.1,
|
|
29
|
+
stream: Any = sys.stdout,
|
|
30
|
+
) -> None:
|
|
31
|
+
self.text = text
|
|
32
|
+
self.delay = delay
|
|
33
|
+
self.stream = stream
|
|
34
|
+
self.frames = _SPINNER_STYLES.get(style, _SPINNER_STYLES["dots"])
|
|
35
|
+
self._stop_event = threading.Event()
|
|
36
|
+
self._thread: threading.Thread | None = None
|
|
37
|
+
|
|
38
|
+
def _spin(self) -> None:
|
|
39
|
+
for frame in itertools.cycle(self.frames):
|
|
40
|
+
if self._stop_event.is_set():
|
|
41
|
+
break
|
|
42
|
+
sys.stdout.write(f"\r{frame} {self.text}")
|
|
43
|
+
sys.stdout.flush()
|
|
44
|
+
time.sleep(self.delay)
|
|
45
|
+
|
|
46
|
+
def start(self) -> Self:
|
|
47
|
+
"""Start the spinner animation thread."""
|
|
48
|
+
if self._thread is not None and self._thread.is_alive():
|
|
49
|
+
return self
|
|
50
|
+
|
|
51
|
+
self._stop_event.clear()
|
|
52
|
+
self._thread = threading.Thread(target=self._spin, daemon=True)
|
|
53
|
+
self._thread.start()
|
|
54
|
+
return self
|
|
55
|
+
|
|
56
|
+
def stop(self, final_text: str | None = None) -> None:
|
|
57
|
+
"""Stop the spinner animation and clear or finalize the line."""
|
|
58
|
+
if self._thread is None:
|
|
59
|
+
return
|
|
60
|
+
|
|
61
|
+
self._stop_event.set()
|
|
62
|
+
self._thread.join()
|
|
63
|
+
self._thread = None
|
|
64
|
+
|
|
65
|
+
# Clear line and print final message if provided
|
|
66
|
+
sys.stdout.write("\r\033[K")
|
|
67
|
+
if final_text:
|
|
68
|
+
self.stream.write(f"{final_text}\n")
|
|
69
|
+
self.stream.flush()
|
|
70
|
+
|
|
71
|
+
def update_text(self, text: str) -> None:
|
|
72
|
+
"""Update the message displayed next to the spinner."""
|
|
73
|
+
self.text = text
|
|
74
|
+
|
|
75
|
+
def __enter__(self) -> Self:
|
|
76
|
+
return self.start()
|
|
77
|
+
|
|
78
|
+
def __exit__(
|
|
79
|
+
self,
|
|
80
|
+
exc_type: type[BaseException] | None,
|
|
81
|
+
exc_val: BaseException | None,
|
|
82
|
+
exc_tb: TracebackType | None,
|
|
83
|
+
) -> None:
|
|
84
|
+
if exc_type is not None:
|
|
85
|
+
self.stop("❌ Failed!")
|
|
86
|
+
else:
|
|
87
|
+
self.stop("✔ Done!")
|
dev_toolkit/color.py
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
__all__ = ["blue", "bold", "green", "red", "yellow"]
|
|
4
|
+
|
|
5
|
+
_RESET = "\033[0m"
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def _colorize(text: str, code: str) -> str:
|
|
9
|
+
return f"\033[{code}m{text}{_RESET}"
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def red(text: str) -> str:
|
|
13
|
+
"""Format text with ANSI red color."""
|
|
14
|
+
return _colorize(text, "31")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def green(text: str) -> str:
|
|
18
|
+
"""Format text with ANSI green color."""
|
|
19
|
+
return _colorize(text, "32")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def yellow(text: str) -> str:
|
|
23
|
+
"""Format text with ANSI yellow color."""
|
|
24
|
+
return _colorize(text, "33")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def blue(text: str) -> str:
|
|
28
|
+
"""Format text with ANSI blue color."""
|
|
29
|
+
return _colorize(text, "34")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def bold(text: str) -> str:
|
|
33
|
+
"""Format text with ANSI bold style."""
|
|
34
|
+
return _colorize(text, "1")
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections.abc import Callable
|
|
4
|
+
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor, as_completed
|
|
5
|
+
from typing import Any, TypeVar
|
|
6
|
+
|
|
7
|
+
__all__ = ["run_parallel", "run_parallel_processes"]
|
|
8
|
+
|
|
9
|
+
T = TypeVar("T")
|
|
10
|
+
R = TypeVar("R")
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def run_parallel(
|
|
14
|
+
func: Callable[[T], R],
|
|
15
|
+
items: list[T],
|
|
16
|
+
max_workers: int | None = None,
|
|
17
|
+
timeout: float | None = None,
|
|
18
|
+
) -> list[R | Exception]:
|
|
19
|
+
"""Execute a function across a list of items in parallel using threads.
|
|
20
|
+
|
|
21
|
+
Returns a list of results or Exceptions if an item fails.
|
|
22
|
+
"""
|
|
23
|
+
results: list[Any] = [None] * len(items)
|
|
24
|
+
with ThreadPoolExecutor(max_workers=max_workers) as executor:
|
|
25
|
+
future_to_index = {
|
|
26
|
+
executor.submit(func, item): i for i, item in enumerate(items)
|
|
27
|
+
}
|
|
28
|
+
for future in as_completed(future_to_index, timeout=timeout):
|
|
29
|
+
index = future_to_index[future]
|
|
30
|
+
try:
|
|
31
|
+
results[index] = future.result()
|
|
32
|
+
except Exception as exc: # noqa: BLE001
|
|
33
|
+
results[index] = exc
|
|
34
|
+
return results
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def run_parallel_processes(
|
|
38
|
+
func: Callable[[T], R],
|
|
39
|
+
items: list[T],
|
|
40
|
+
max_workers: int | None = None,
|
|
41
|
+
timeout: float | None = None,
|
|
42
|
+
) -> list[R | Exception]:
|
|
43
|
+
"""Execute a function across a list of items in parallel using processes.
|
|
44
|
+
|
|
45
|
+
Returns a list of results or Exceptions if an item fails.
|
|
46
|
+
"""
|
|
47
|
+
results: list[Any] = [None] * len(items)
|
|
48
|
+
with ProcessPoolExecutor(max_workers=max_workers) as executor:
|
|
49
|
+
future_to_index = {
|
|
50
|
+
executor.submit(func, item): i for i, item in enumerate(items)
|
|
51
|
+
}
|
|
52
|
+
for future in as_completed(future_to_index, timeout=timeout):
|
|
53
|
+
index = future_to_index[future]
|
|
54
|
+
try:
|
|
55
|
+
results[index] = future.result()
|
|
56
|
+
except Exception as exc: # noqa: BLE001
|
|
57
|
+
results[index] = exc
|
|
58
|
+
return results
|
dev_toolkit/config.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
|
|
5
|
+
os = __import__("os")
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
__all__ = ["ConfigManager"]
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class ConfigManager:
|
|
13
|
+
"""A robust configuration manager supporting defaults, JSON file loading,
|
|
14
|
+
|
|
15
|
+
and environment variable overrides with prefix matching.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
def __init__(
|
|
19
|
+
self,
|
|
20
|
+
defaults: dict[str, Any] | None = None,
|
|
21
|
+
config_path: str | Path | None = None,
|
|
22
|
+
env_prefix: str | None = None,
|
|
23
|
+
) -> None:
|
|
24
|
+
self._data: dict[str, Any] = defaults.copy() if defaults else {}
|
|
25
|
+
self.config_path = Path(config_path) if config_path else None
|
|
26
|
+
self.env_prefix = env_prefix
|
|
27
|
+
|
|
28
|
+
if self.config_path and self.config_path.exists():
|
|
29
|
+
self.load_file(self.config_path)
|
|
30
|
+
|
|
31
|
+
if self.env_prefix:
|
|
32
|
+
self.load_env(self.env_prefix)
|
|
33
|
+
|
|
34
|
+
def load_file(self, path: str | Path) -> None:
|
|
35
|
+
"""Load and merge configuration from a JSON file."""
|
|
36
|
+
file_path = Path(path)
|
|
37
|
+
if file_path.exists():
|
|
38
|
+
with open(file_path, "r", encoding="utf-8") as f:
|
|
39
|
+
content = json.load(f)
|
|
40
|
+
if isinstance(content, dict):
|
|
41
|
+
self._data.update(content)
|
|
42
|
+
|
|
43
|
+
def load_env(self, prefix: str) -> None:
|
|
44
|
+
"""Override configuration values using environment variables matching the prefix."""
|
|
45
|
+
prefix_upper = prefix.upper() + "_"
|
|
46
|
+
for key, val in os.environ.items():
|
|
47
|
+
if key.startswith(prefix_upper):
|
|
48
|
+
config_key = key[len(prefix_upper) :].lower()
|
|
49
|
+
# Try parsing JSON primitives (bool, int, float), fallback to string
|
|
50
|
+
try:
|
|
51
|
+
parsed_val = json.loads(val)
|
|
52
|
+
except (json.JSONDecodeError, TypeError):
|
|
53
|
+
parsed_val = val
|
|
54
|
+
self._data[config_key] = parsed_val
|
|
55
|
+
|
|
56
|
+
def get(self, key: str, default: Any = None) -> Any:
|
|
57
|
+
"""Retrieve a configuration value by key."""
|
|
58
|
+
return self._data.get(key, default)
|
|
59
|
+
|
|
60
|
+
def set(self, key: str, value: Any) -> None:
|
|
61
|
+
"""Set a configuration value."""
|
|
62
|
+
self._data[key] = value
|
|
63
|
+
|
|
64
|
+
def to_dict(self) -> dict[str, Any]:
|
|
65
|
+
"""Return a copy of the full configuration dictionary."""
|
|
66
|
+
return self._data.copy()
|
|
67
|
+
|
|
68
|
+
def save(self, path: str | Path | None = None) -> None:
|
|
69
|
+
"""Save the current configuration to a JSON file."""
|
|
70
|
+
target = Path(path) if path else self.config_path
|
|
71
|
+
if not target:
|
|
72
|
+
raise ValueError("No configuration file path specified.")
|
|
73
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
74
|
+
with open(target, "w", encoding="utf-8") as f:
|
|
75
|
+
json.dump(self._data, f, indent=4)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
import secrets
|
|
5
|
+
|
|
6
|
+
__all__ = ["generate_token", "md5_hash", "sha256_hash"]
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def generate_token(length: int = 32) -> str:
|
|
10
|
+
"""Generate a secure URL-safe random token."""
|
|
11
|
+
return secrets.token_hex(length)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def sha256_hash(text: str) -> str:
|
|
15
|
+
"""Compute the SHA-256 cryptographic hash of a string."""
|
|
16
|
+
return hashlib.sha256(text.encode("utf-8")).hexdigest()
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def md5_hash(text: str) -> str:
|
|
20
|
+
"""Compute the MD5 hash of a string."""
|
|
21
|
+
return hashlib.md5(text.encode("utf-8")).hexdigest()
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""Function decorators for common runtime behavior modifications."""
|
|
2
|
+
|
|
3
|
+
import functools
|
|
4
|
+
import random
|
|
5
|
+
import time
|
|
6
|
+
from collections.abc import Callable
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def retry(
|
|
11
|
+
max_attempts: int = 3,
|
|
12
|
+
delay: float = 1.0,
|
|
13
|
+
backoff_factor: float = 2.0,
|
|
14
|
+
jitter: bool = True,
|
|
15
|
+
exceptions: tuple[type[Exception], ...] = (Exception,),
|
|
16
|
+
on_retry: Callable[[Exception, int], None] | None = None,
|
|
17
|
+
) -> Callable[..., Any]:
|
|
18
|
+
"""Decorator to retry a function invocation with backoff and optional jitter."""
|
|
19
|
+
if max_attempts < 1:
|
|
20
|
+
raise ValueError("max_attempts must be at least 1")
|
|
21
|
+
if delay < 0:
|
|
22
|
+
raise ValueError("delay cannot be negative")
|
|
23
|
+
|
|
24
|
+
def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
|
|
25
|
+
@functools.wraps(func)
|
|
26
|
+
def wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
27
|
+
current_delay = delay
|
|
28
|
+
for attempt in range(1, max_attempts + 1):
|
|
29
|
+
try:
|
|
30
|
+
return func(*args, **kwargs)
|
|
31
|
+
except exceptions as err:
|
|
32
|
+
if attempt == max_attempts:
|
|
33
|
+
raise
|
|
34
|
+
|
|
35
|
+
if on_retry:
|
|
36
|
+
on_retry(err, attempt)
|
|
37
|
+
|
|
38
|
+
sleep_time = current_delay
|
|
39
|
+
if jitter:
|
|
40
|
+
sleep_time = random.uniform(0, current_delay)
|
|
41
|
+
|
|
42
|
+
time.sleep(sleep_time)
|
|
43
|
+
current_delay *= backoff_factor
|
|
44
|
+
|
|
45
|
+
return wrapper
|
|
46
|
+
|
|
47
|
+
return decorator
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Dictionary and sequence manipulation utilities."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Callable, Generator, Sequence
|
|
4
|
+
from typing import Any, TypeVar
|
|
5
|
+
|
|
6
|
+
T = TypeVar("T")
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def get_in(data: dict[str, Any], keys: list[str], default: Any = None) -> Any:
|
|
10
|
+
"""Safely extract nested dictionary values using a key path."""
|
|
11
|
+
curr = data
|
|
12
|
+
for k in keys:
|
|
13
|
+
if isinstance(curr, dict) and k in curr:
|
|
14
|
+
curr = curr[k]
|
|
15
|
+
else:
|
|
16
|
+
return default
|
|
17
|
+
return curr
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def flatten_dict(
|
|
21
|
+
d: dict[str, Any], parent_key: str = "", sep: str = "."
|
|
22
|
+
) -> dict[str, Any]:
|
|
23
|
+
"""Flatten nested dictionary keys into single string paths."""
|
|
24
|
+
items: list[tuple[str, Any]] = []
|
|
25
|
+
for k, v in d.items():
|
|
26
|
+
new_key = f"{parent_key}{sep}{k}" if parent_key else k
|
|
27
|
+
if isinstance(v, dict):
|
|
28
|
+
items.extend(flatten_dict(v, new_key, sep=sep).items())
|
|
29
|
+
else:
|
|
30
|
+
items.append((new_key, v))
|
|
31
|
+
return dict(items)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def deep_merge(dict1: dict[str, Any], dict2: dict[str, Any]) -> dict[str, Any]:
|
|
35
|
+
"""Recursively merge two dictionaries."""
|
|
36
|
+
result = dict(dict1)
|
|
37
|
+
for k, v in dict2.items():
|
|
38
|
+
if k in result and isinstance(result[k], dict) and isinstance(v, dict):
|
|
39
|
+
result[k] = deep_merge(result[k], v)
|
|
40
|
+
else:
|
|
41
|
+
result[k] = v
|
|
42
|
+
return result
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def pick(d: dict[str, Any], keys: Sequence[str]) -> dict[str, Any]:
|
|
46
|
+
"""Return a dictionary containing only the specified keys."""
|
|
47
|
+
key_set = set(keys)
|
|
48
|
+
return {k: v for k, v in d.items() if k in key_set}
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def omit(d: dict[str, Any], keys: Sequence[str]) -> dict[str, Any]:
|
|
52
|
+
"""Return a dictionary excluding the specified keys."""
|
|
53
|
+
key_set = set(keys)
|
|
54
|
+
return {k: v for k, v in d.items() if k not in key_set}
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def filter_keys(
|
|
58
|
+
d: dict[str, Any], predicate: Callable[[str, Any], bool]
|
|
59
|
+
) -> dict[str, Any]:
|
|
60
|
+
"""Recursively filter a dictionary by key-value predicate function."""
|
|
61
|
+
res: dict[str, Any] = {}
|
|
62
|
+
for k, v in d.items():
|
|
63
|
+
if isinstance(v, dict):
|
|
64
|
+
filtered_v = filter_keys(v, predicate)
|
|
65
|
+
if predicate(k, filtered_v):
|
|
66
|
+
res[k] = filtered_v
|
|
67
|
+
elif predicate(k, v):
|
|
68
|
+
res[k] = v
|
|
69
|
+
return res
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def chunk_list(items: Sequence[T], chunk_size: int) -> Generator[list[T], None, None]:
|
|
73
|
+
"""Yield successive fixed-size chunks from a sequence."""
|
|
74
|
+
if chunk_size <= 0:
|
|
75
|
+
raise ValueError("chunk_size must be strictly positive")
|
|
76
|
+
for i in range(0, len(items), chunk_size):
|
|
77
|
+
yield list(items[i : i + chunk_size])
|
dev_toolkit/encoding.py
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import base64
|
|
4
|
+
|
|
5
|
+
__all__ = ["base64_decode", "base64_encode"]
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def base64_encode(data: str | bytes) -> str:
|
|
9
|
+
"""Encode a string or bytes into a Base64 string."""
|
|
10
|
+
if isinstance(data, str):
|
|
11
|
+
data_bytes = data.encode("utf-8")
|
|
12
|
+
else:
|
|
13
|
+
data_bytes = data
|
|
14
|
+
return base64.b64encode(data_bytes).decode("utf-8")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def base64_decode(encoded_str: str) -> str:
|
|
18
|
+
"""Decode a Base64 string back to a UTF-8 string."""
|
|
19
|
+
return base64.b64decode(encoded_str.encode("utf-8")).decode("utf-8")
|
dev_toolkit/env.py
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""Environment variable helpers and validation utilities."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def check_required_env(required_vars: list[str]) -> list[str]:
|
|
7
|
+
"""Return a list of required environment variable names that are missing."""
|
|
8
|
+
return [var for var in required_vars if var not in os.environ]
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def mask_secret(secret: str, visible_chars: int = 4) -> str:
|
|
12
|
+
"""Mask a sensitive string, leaving only the last few characters visible."""
|
|
13
|
+
if len(secret) <= visible_chars:
|
|
14
|
+
return "*" * len(secret)
|
|
15
|
+
return "*" * (len(secret) - visible_chars) + secret[-visible_chars:]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def get_env_summary() -> dict[str, bool]:
|
|
19
|
+
"""Check standard developer environment flags."""
|
|
20
|
+
return {
|
|
21
|
+
"DEBUG": os.getenv("DEBUG", "0").lower() in ("1", "true", "yes"),
|
|
22
|
+
"CI": os.getenv("CI", "0").lower() in ("1", "true", "yes"),
|
|
23
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
__all__ = ["get_env_or_raise", "validate_env"]
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def get_env_or_raise(key: str, default: Any = None) -> str:
|
|
10
|
+
"""Get an environment variable or raise a ValueError if missing."""
|
|
11
|
+
val = os.getenv(key, default)
|
|
12
|
+
if val is None or val == "":
|
|
13
|
+
raise ValueError(f"Required environment variable '{key}' is missing or empty.")
|
|
14
|
+
return str(val)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def validate_env(required_keys: list[str]) -> dict[str, str]:
|
|
18
|
+
"""Validate that multiple required environment variables are set."""
|
|
19
|
+
missing = [key for key in required_keys if not os.getenv(key)]
|
|
20
|
+
if missing:
|
|
21
|
+
raise ValueError(
|
|
22
|
+
f"Missing required environment variables: {', '.join(missing)}"
|
|
23
|
+
)
|
|
24
|
+
return {key: os.environ[key] for key in required_keys}
|
dev_toolkit/events.py
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections import defaultdict
|
|
4
|
+
from collections.abc import Callable
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
__all__ = ["EventEmitter"]
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class EventEmitter:
|
|
11
|
+
"""A simple, robust event emitter (pub-sub) implementation."""
|
|
12
|
+
|
|
13
|
+
def __init__(self) -> None:
|
|
14
|
+
self._listeners: dict[str, list[Callable[..., Any]]] = defaultdict(list)
|
|
15
|
+
|
|
16
|
+
def on(self, event: str, listener: Callable[..., Any]) -> EventEmitter:
|
|
17
|
+
"""Register an event listener for a given event name."""
|
|
18
|
+
self._listeners[event].append(listener)
|
|
19
|
+
return self
|
|
20
|
+
|
|
21
|
+
def off(self, event: str, listener: Callable[..., Any]) -> EventEmitter:
|
|
22
|
+
"""Remove a specific listener from an event name."""
|
|
23
|
+
if event in self._listeners:
|
|
24
|
+
try:
|
|
25
|
+
self._listeners[event].remove(listener)
|
|
26
|
+
except ValueError:
|
|
27
|
+
pass
|
|
28
|
+
return self
|
|
29
|
+
|
|
30
|
+
def emit(self, event: str, *args: Any, **kwargs: Any) -> list[Any]:
|
|
31
|
+
"""Emit an event, invoking all registered listeners with provided arguments."""
|
|
32
|
+
results = []
|
|
33
|
+
for listener in list(self._listeners[event]):
|
|
34
|
+
results.append(listener(*args, **kwargs))
|
|
35
|
+
return results
|
|
36
|
+
|
|
37
|
+
def once(self, event: str, listener: Callable[..., Any]) -> EventEmitter:
|
|
38
|
+
"""Register a listener that automatically unregisters after its first invocation."""
|
|
39
|
+
|
|
40
|
+
def wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
41
|
+
self.off(event, wrapper)
|
|
42
|
+
return listener(*args, **kwargs)
|
|
43
|
+
|
|
44
|
+
return self.on(event, wrapper)
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""Human-readable string formatting utilities."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
def format_bytes(size: float, binary: bool = True) -> str:
|
|
5
|
+
"""Format a byte count into a human-readable string (e.g., 1.50 MiB or 1.50 MB)."""
|
|
6
|
+
if size < 0:
|
|
7
|
+
raise ValueError("Size cannot be negative")
|
|
8
|
+
|
|
9
|
+
factor = 1024.0 if binary else 1000.0
|
|
10
|
+
units = (
|
|
11
|
+
["B", "KiB", "MiB", "GiB", "TiB", "PiB"]
|
|
12
|
+
if binary
|
|
13
|
+
else ["B", "KB", "MB", "GB", "TB", "PB"]
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
current_size = float(size)
|
|
17
|
+
for unit in units[:-1]:
|
|
18
|
+
if current_size < factor:
|
|
19
|
+
return f"{current_size:.2f} {unit}"
|
|
20
|
+
current_size /= factor
|
|
21
|
+
|
|
22
|
+
return f"{current_size:.2f} {units[-1]}"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def format_duration(seconds: float) -> str:
|
|
26
|
+
"""Format seconds into a compact human-readable duration (e.g., '2h 14m 30s')."""
|
|
27
|
+
if seconds < 0:
|
|
28
|
+
raise ValueError("Duration cannot be negative")
|
|
29
|
+
|
|
30
|
+
if seconds == 0:
|
|
31
|
+
return "0s"
|
|
32
|
+
|
|
33
|
+
total = int(seconds)
|
|
34
|
+
hours, remainder = divmod(total, 3600)
|
|
35
|
+
minutes, secs = divmod(remainder, 60)
|
|
36
|
+
|
|
37
|
+
parts: list[str] = []
|
|
38
|
+
if hours > 0:
|
|
39
|
+
parts.append(f"{hours}h")
|
|
40
|
+
if minutes > 0:
|
|
41
|
+
parts.append(f"{minutes}m")
|
|
42
|
+
if secs > 0 or not parts:
|
|
43
|
+
parts.append(f"{secs}s")
|
|
44
|
+
|
|
45
|
+
return " ".join(parts)
|
dev_toolkit/hash.py
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Hashing and checksum calculation utilities."""
|
|
2
|
+
|
|
3
|
+
import hashlib
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def get_str_hash(text: str, algorithm: str = "sha256") -> str:
|
|
8
|
+
"""Calculate the hexadecimal hash digest of a string."""
|
|
9
|
+
try:
|
|
10
|
+
hasher = hashlib.new(algorithm)
|
|
11
|
+
except ValueError as err:
|
|
12
|
+
raise ValueError(f"Unsupported hash algorithm: '{algorithm}'") from err
|
|
13
|
+
|
|
14
|
+
hasher.update(text.encode("utf-8"))
|
|
15
|
+
return hasher.hexdigest()
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def get_file_hash(
|
|
19
|
+
path: str | Path,
|
|
20
|
+
algorithm: str = "sha256",
|
|
21
|
+
chunk_size: int = 65536,
|
|
22
|
+
) -> str:
|
|
23
|
+
"""Calculate the hexadecimal hash digest of a file using chunked reading."""
|
|
24
|
+
file_path = Path(path)
|
|
25
|
+
if not file_path.is_file():
|
|
26
|
+
raise FileNotFoundError(f"File not found: {file_path}")
|
|
27
|
+
|
|
28
|
+
try:
|
|
29
|
+
hasher = hashlib.new(algorithm)
|
|
30
|
+
except ValueError as err:
|
|
31
|
+
raise ValueError(f"Unsupported hash algorithm: '{algorithm}'") from err
|
|
32
|
+
|
|
33
|
+
with open(file_path, "rb") as f:
|
|
34
|
+
while chunk := f.read(chunk_size):
|
|
35
|
+
hasher.update(chunk)
|
|
36
|
+
|
|
37
|
+
return hasher.hexdigest()
|
dev_toolkit/http.py
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""Asynchronous HTTP request utilities."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import json
|
|
5
|
+
from typing import Any
|
|
6
|
+
from urllib.request import Request, urlopen
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
async def fetch_json(
|
|
10
|
+
url: str,
|
|
11
|
+
headers: dict[str, str] | None = None,
|
|
12
|
+
timeout: float = 10.0,
|
|
13
|
+
) -> dict[str, Any]:
|
|
14
|
+
"""Fetch JSON payload asynchronously from a URL."""
|
|
15
|
+
req = Request(url, headers=headers or {})
|
|
16
|
+
|
|
17
|
+
def _sync_fetch() -> dict[str, Any]:
|
|
18
|
+
with urlopen(req, timeout=timeout) as response:
|
|
19
|
+
data = response.read().decode("utf-8")
|
|
20
|
+
return json.loads(data)
|
|
21
|
+
|
|
22
|
+
return await asyncio.to_thread(_sync_fetch)
|
dev_toolkit/io.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Utilities for safe file operations, JSON processing, and directory management."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def ensure_dir(dir_path: str | Path) -> Path:
|
|
9
|
+
"""Ensure a directory exists, creating missing parent folders if needed."""
|
|
10
|
+
path = Path(dir_path)
|
|
11
|
+
path.mkdir(parents=True, exist_ok=True)
|
|
12
|
+
return path
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def read_json(file_path: str | Path) -> dict[str, Any]:
|
|
16
|
+
"""Safely load and parse a JSON file."""
|
|
17
|
+
path = Path(file_path)
|
|
18
|
+
if not path.exists():
|
|
19
|
+
raise FileNotFoundError(f"Target JSON file does not exist: {path}")
|
|
20
|
+
with path.open("r", encoding="utf-8") as f:
|
|
21
|
+
return json.load(f)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def write_json(
|
|
25
|
+
file_path: str | Path,
|
|
26
|
+
data: Any,
|
|
27
|
+
indent: int = 2,
|
|
28
|
+
overwrite: bool = True,
|
|
29
|
+
) -> Path:
|
|
30
|
+
"""Write data to a JSON file, creating parent directories as necessary."""
|
|
31
|
+
path = Path(file_path)
|
|
32
|
+
if path.exists() and not overwrite:
|
|
33
|
+
raise FileExistsError(
|
|
34
|
+
f"File already exists and overwrite is set to False: {path}"
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
ensure_dir(path.parent)
|
|
38
|
+
with path.open("w", encoding="utf-8") as f:
|
|
39
|
+
json.dump(data, f, indent=indent)
|
|
40
|
+
return path
|