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.
Files changed (45) hide show
  1. azrvus_dev_toolkit-0.1.0.dist-info/METADATA +113 -0
  2. azrvus_dev_toolkit-0.1.0.dist-info/RECORD +45 -0
  3. azrvus_dev_toolkit-0.1.0.dist-info/WHEEL +4 -0
  4. azrvus_dev_toolkit-0.1.0.dist-info/entry_points.txt +2 -0
  5. azrvus_dev_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  6. dev_toolkit/__init__.py +163 -0
  7. dev_toolkit/_version.py +3 -0
  8. dev_toolkit/async_io.py +19 -0
  9. dev_toolkit/banner.py +37 -0
  10. dev_toolkit/cache.py +88 -0
  11. dev_toolkit/cli.py +60 -0
  12. dev_toolkit/cli_formatters.py +79 -0
  13. dev_toolkit/cli_spinner.py +87 -0
  14. dev_toolkit/color.py +34 -0
  15. dev_toolkit/concurrency.py +58 -0
  16. dev_toolkit/config.py +75 -0
  17. dev_toolkit/crypto_utils.py +21 -0
  18. dev_toolkit/decorators.py +47 -0
  19. dev_toolkit/dict_utils.py +77 -0
  20. dev_toolkit/encoding.py +19 -0
  21. dev_toolkit/env.py +23 -0
  22. dev_toolkit/env_validator.py +24 -0
  23. dev_toolkit/events.py +44 -0
  24. dev_toolkit/formatters.py +45 -0
  25. dev_toolkit/hash.py +37 -0
  26. dev_toolkit/http.py +22 -0
  27. dev_toolkit/io.py +40 -0
  28. dev_toolkit/jsonl.py +62 -0
  29. dev_toolkit/logger.py +36 -0
  30. dev_toolkit/masking.py +51 -0
  31. dev_toolkit/pagination.py +29 -0
  32. dev_toolkit/path_utils.py +84 -0
  33. dev_toolkit/process.py +65 -0
  34. dev_toolkit/random_utils.py +19 -0
  35. dev_toolkit/rate_limiter.py +77 -0
  36. dev_toolkit/retry.py +37 -0
  37. dev_toolkit/retry_utils.py +93 -0
  38. dev_toolkit/system.py +24 -0
  39. dev_toolkit/templating.py +28 -0
  40. dev_toolkit/text.py +45 -0
  41. dev_toolkit/timer.py +41 -0
  42. dev_toolkit/transforms.py +21 -0
  43. dev_toolkit/url_utils.py +35 -0
  44. dev_toolkit/validators.py +74 -0
  45. 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])
@@ -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