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,244 @@
|
|
|
1
|
+
"""JSON utilities for DevKitX.
|
|
2
|
+
|
|
3
|
+
This module provides utilities for loading, saving, and manipulating JSON data
|
|
4
|
+
with enhanced error handling and formatting options.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def load_json(path: str | Path) -> dict:
|
|
15
|
+
"""Load JSON data from file.
|
|
16
|
+
|
|
17
|
+
Args:
|
|
18
|
+
path: Path to JSON file
|
|
19
|
+
|
|
20
|
+
Returns:
|
|
21
|
+
Parsed JSON data as dictionary
|
|
22
|
+
|
|
23
|
+
Raises:
|
|
24
|
+
FileNotFoundError: If the file doesn't exist
|
|
25
|
+
json.JSONDecodeError: If the file contains invalid JSON
|
|
26
|
+
PermissionError: If lacking read permissions
|
|
27
|
+
|
|
28
|
+
Examples:
|
|
29
|
+
>>> data = load_json("config.json")
|
|
30
|
+
>>> data = load_json(Path("data/settings.json"))
|
|
31
|
+
"""
|
|
32
|
+
p = Path(path)
|
|
33
|
+
with p.open("r", encoding="utf-8") as f:
|
|
34
|
+
return json.load(f)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def save_json(data: Any, path: str | Path, *, pretty: bool = True) -> None:
|
|
38
|
+
"""Save data to JSON file.
|
|
39
|
+
|
|
40
|
+
Args:
|
|
41
|
+
data: Data to save as JSON
|
|
42
|
+
path: Path to save JSON file
|
|
43
|
+
pretty: Whether to format JSON with indentation and sorting
|
|
44
|
+
|
|
45
|
+
Raises:
|
|
46
|
+
PermissionError: If lacking write permissions
|
|
47
|
+
OSError: If unable to create parent directories
|
|
48
|
+
TypeError: If data is not JSON serializable
|
|
49
|
+
|
|
50
|
+
Examples:
|
|
51
|
+
>>> save_json({"name": "John", "age": 30}, "user.json")
|
|
52
|
+
>>> save_json([1, 2, 3], "numbers.json", pretty=False)
|
|
53
|
+
>>> save_json(data, Path("output/result.json"))
|
|
54
|
+
"""
|
|
55
|
+
p = Path(path)
|
|
56
|
+
p.parent.mkdir(parents=True, exist_ok=True)
|
|
57
|
+
with p.open("w", encoding="utf-8") as f:
|
|
58
|
+
if pretty:
|
|
59
|
+
json.dump(data, f, ensure_ascii=False, indent=2, sort_keys=True)
|
|
60
|
+
f.write("\n")
|
|
61
|
+
else:
|
|
62
|
+
json.dump(data, f, ensure_ascii=False, separators=(",", ":"))
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def pretty_json(data: Any, *, color: bool = False) -> str:
|
|
66
|
+
"""Format data as pretty-printed JSON string.
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
data: Data to format as JSON
|
|
70
|
+
color: Whether to add syntax highlighting (requires pygments)
|
|
71
|
+
|
|
72
|
+
Returns:
|
|
73
|
+
Pretty-formatted JSON string
|
|
74
|
+
|
|
75
|
+
Raises:
|
|
76
|
+
TypeError: If data is not JSON serializable
|
|
77
|
+
|
|
78
|
+
Examples:
|
|
79
|
+
>>> data = {"name": "John", "items": [1, 2, 3]}
|
|
80
|
+
>>> print(pretty_json(data))
|
|
81
|
+
{
|
|
82
|
+
"items": [
|
|
83
|
+
1,
|
|
84
|
+
2,
|
|
85
|
+
3
|
|
86
|
+
],
|
|
87
|
+
"name": "John"
|
|
88
|
+
}
|
|
89
|
+
>>> colored = pretty_json(data, color=True) # Adds syntax highlighting
|
|
90
|
+
"""
|
|
91
|
+
s = json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True)
|
|
92
|
+
if not color:
|
|
93
|
+
return s
|
|
94
|
+
try:
|
|
95
|
+
# Optional colorization if pygments is present (no hard dep)
|
|
96
|
+
from pygments import highlight # type: ignore
|
|
97
|
+
from pygments.formatters import TerminalFormatter # type: ignore
|
|
98
|
+
from pygments.lexers import JsonLexer # type: ignore
|
|
99
|
+
|
|
100
|
+
return highlight(s, JsonLexer(), TerminalFormatter())
|
|
101
|
+
except Exception:
|
|
102
|
+
return s
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def detect_jsonl(path: str | Path, *, sample: int = 10) -> bool:
|
|
106
|
+
"""Detect if file contains JSON Lines (NDJSON) format.
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
path: Path to file to check
|
|
110
|
+
sample: Number of lines to sample for detection
|
|
111
|
+
|
|
112
|
+
Returns:
|
|
113
|
+
True if file appears to be JSON Lines format, False otherwise
|
|
114
|
+
|
|
115
|
+
Raises:
|
|
116
|
+
FileNotFoundError: If the file doesn't exist
|
|
117
|
+
PermissionError: If lacking read permissions
|
|
118
|
+
|
|
119
|
+
Examples:
|
|
120
|
+
>>> detect_jsonl("data.jsonl")
|
|
121
|
+
True
|
|
122
|
+
>>> detect_jsonl("regular.json")
|
|
123
|
+
False
|
|
124
|
+
>>> detect_jsonl("mixed.txt", sample=5) # Check first 5 lines
|
|
125
|
+
False
|
|
126
|
+
"""
|
|
127
|
+
p = Path(path)
|
|
128
|
+
with p.open("r", encoding="utf-8") as f:
|
|
129
|
+
for i, line in enumerate(f):
|
|
130
|
+
if i >= sample:
|
|
131
|
+
break
|
|
132
|
+
line = line.strip()
|
|
133
|
+
if not line:
|
|
134
|
+
continue
|
|
135
|
+
try:
|
|
136
|
+
json.loads(line)
|
|
137
|
+
except json.JSONDecodeError:
|
|
138
|
+
return False
|
|
139
|
+
return True
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def flatten_json(obj: dict, sep: str = ".") -> dict[str, Any]:
|
|
143
|
+
"""Flatten nested JSON object into dot-notation keys.
|
|
144
|
+
|
|
145
|
+
Args:
|
|
146
|
+
obj: Dictionary to flatten
|
|
147
|
+
sep: Separator to use between nested keys
|
|
148
|
+
|
|
149
|
+
Returns:
|
|
150
|
+
Flattened dictionary with dot-notation keys
|
|
151
|
+
|
|
152
|
+
Examples:
|
|
153
|
+
>>> nested = {"user": {"name": "John", "details": {"age": 30}}}
|
|
154
|
+
>>> flatten_json(nested)
|
|
155
|
+
{'user.name': 'John', 'user.details.age': 30}
|
|
156
|
+
>>> flatten_json({"items": [1, 2, 3]})
|
|
157
|
+
{'items.0': 1, 'items.1': 2, 'items.2': 3}
|
|
158
|
+
>>> flatten_json(nested, sep="_")
|
|
159
|
+
{'user_name': 'John', 'user_details_age': 30}
|
|
160
|
+
"""
|
|
161
|
+
out: dict[str, Any] = {}
|
|
162
|
+
|
|
163
|
+
def _rec(prefix: str, value: Any) -> None:
|
|
164
|
+
if isinstance(value, dict):
|
|
165
|
+
for k, v in value.items():
|
|
166
|
+
_rec(f"{prefix}{k}{sep}" if prefix else f"{k}{sep}", v)
|
|
167
|
+
elif isinstance(value, list):
|
|
168
|
+
for i, v in enumerate(value):
|
|
169
|
+
_rec(f"{prefix}{i}{sep}", v)
|
|
170
|
+
else:
|
|
171
|
+
key = prefix[: -len(sep)] if prefix.endswith(sep) else prefix
|
|
172
|
+
out[key] = value
|
|
173
|
+
|
|
174
|
+
_rec("", obj)
|
|
175
|
+
return out
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def unflatten_json(flat: dict[str, Any], sep: str = ".") -> dict[str, Any]:
|
|
179
|
+
"""Unflatten dot-notation keys back into nested JSON object.
|
|
180
|
+
|
|
181
|
+
Args:
|
|
182
|
+
flat: Flattened dictionary with dot-notation keys
|
|
183
|
+
sep: Separator used between nested keys
|
|
184
|
+
|
|
185
|
+
Returns:
|
|
186
|
+
Nested dictionary structure
|
|
187
|
+
|
|
188
|
+
Raises:
|
|
189
|
+
TypeError: If there are conflicting path types (dict vs list)
|
|
190
|
+
|
|
191
|
+
Examples:
|
|
192
|
+
>>> flat = {'user.name': 'John', 'user.details.age': 30}
|
|
193
|
+
>>> unflatten_json(flat)
|
|
194
|
+
{'user': {'name': 'John', 'details': {'age': 30}}}
|
|
195
|
+
>>> flat = {'items.0': 1, 'items.1': 2, 'items.2': 3}
|
|
196
|
+
>>> unflatten_json(flat)
|
|
197
|
+
{'items': [1, 2, 3]}
|
|
198
|
+
>>> unflatten_json({'a_b_c': 1}, sep="_")
|
|
199
|
+
{'a': {'b': {'c': 1}}}
|
|
200
|
+
"""
|
|
201
|
+
root: dict[str, Any] = {}
|
|
202
|
+
for k, v in flat.items():
|
|
203
|
+
parts_list = k.split(sep) if k else []
|
|
204
|
+
cur = root
|
|
205
|
+
for i, part in enumerate(parts_list):
|
|
206
|
+
last = i == len(parts_list) - 1
|
|
207
|
+
# numeric index implies list
|
|
208
|
+
idx = None
|
|
209
|
+
if part.isdigit():
|
|
210
|
+
idx = int(part)
|
|
211
|
+
|
|
212
|
+
if last:
|
|
213
|
+
if idx is None:
|
|
214
|
+
if isinstance(cur, list):
|
|
215
|
+
raise TypeError("Cannot set dict key on a list path")
|
|
216
|
+
cur[part] = v
|
|
217
|
+
else:
|
|
218
|
+
if not isinstance(cur, list):
|
|
219
|
+
raise TypeError("Cannot set list index on a dict path")
|
|
220
|
+
# grow list
|
|
221
|
+
while len(cur) <= idx:
|
|
222
|
+
cur.append(None)
|
|
223
|
+
cur[idx] = v
|
|
224
|
+
else:
|
|
225
|
+
nxt = None
|
|
226
|
+
nxt_part = parts_list[i + 1]
|
|
227
|
+
nxt_is_index = nxt_part.isdigit()
|
|
228
|
+
if idx is None:
|
|
229
|
+
# dict path
|
|
230
|
+
if part not in cur or cur[part] is None:
|
|
231
|
+
cur[part] = [] if nxt_is_index else {}
|
|
232
|
+
nxt = cur[part]
|
|
233
|
+
else:
|
|
234
|
+
# list path
|
|
235
|
+
if not isinstance(cur, list):
|
|
236
|
+
# initialize as list
|
|
237
|
+
raise TypeError("Unexpected structure while unflattening")
|
|
238
|
+
while len(cur) <= idx:
|
|
239
|
+
cur.append(None)
|
|
240
|
+
if cur[idx] is None:
|
|
241
|
+
cur[idx] = [] if nxt_is_index else {}
|
|
242
|
+
nxt = cur[idx]
|
|
243
|
+
cur = nxt
|
|
244
|
+
return root
|
devtools_py/log_utils.py
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
"""Logging utilities for DevKitX.
|
|
2
|
+
|
|
3
|
+
This module provides utilities for setting up logging, timing operations,
|
|
4
|
+
and decorating functions with logging capabilities.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import logging
|
|
10
|
+
import sys
|
|
11
|
+
import time
|
|
12
|
+
from contextlib import contextmanager
|
|
13
|
+
from typing import Any, Callable, TypeVar
|
|
14
|
+
|
|
15
|
+
_T = TypeVar("_T")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def setup_logging(
|
|
19
|
+
level: str = "INFO",
|
|
20
|
+
to_file: str | None = None,
|
|
21
|
+
json: bool = False,
|
|
22
|
+
use_loguru: bool = False,
|
|
23
|
+
) -> logging.Logger:
|
|
24
|
+
"""Set up logging configuration for applications.
|
|
25
|
+
|
|
26
|
+
Note: Libraries should not call this function by default as it configures
|
|
27
|
+
global logging state. This is intended for application entry points.
|
|
28
|
+
|
|
29
|
+
Args:
|
|
30
|
+
level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
|
|
31
|
+
to_file: Optional file path to write logs to
|
|
32
|
+
json: Whether to format logs as JSON
|
|
33
|
+
use_loguru: Whether to use loguru library if available
|
|
34
|
+
|
|
35
|
+
Returns:
|
|
36
|
+
Configured logger instance
|
|
37
|
+
|
|
38
|
+
Examples:
|
|
39
|
+
>>> logger = setup_logging("DEBUG")
|
|
40
|
+
>>> logger = setup_logging("INFO", to_file="app.log")
|
|
41
|
+
>>> logger = setup_logging("INFO", json=True, use_loguru=True)
|
|
42
|
+
"""
|
|
43
|
+
if use_loguru:
|
|
44
|
+
try:
|
|
45
|
+
from loguru import logger as _loguru # type: ignore
|
|
46
|
+
|
|
47
|
+
_loguru.remove()
|
|
48
|
+
fmt = (
|
|
49
|
+
'{{"time": "{time}", "level": "{level}", "message": "{message}"}}'
|
|
50
|
+
if json
|
|
51
|
+
else "<green>{time}</green> | <level>{level}</level> | <cyan>{message}</cyan>"
|
|
52
|
+
)
|
|
53
|
+
sink = to_file or sys.stderr
|
|
54
|
+
_loguru.add(sink, format=fmt, level=level)
|
|
55
|
+
|
|
56
|
+
# bridge to stdlib logger
|
|
57
|
+
class Intercept(logging.Handler):
|
|
58
|
+
def emit(self, record: logging.LogRecord) -> None:
|
|
59
|
+
_loguru.opt(depth=6, exception=record.exc_info).log(
|
|
60
|
+
record.levelname, record.getMessage()
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
logging.basicConfig(
|
|
64
|
+
handlers=[Intercept()], level=getattr(logging, level.upper(), logging.INFO)
|
|
65
|
+
)
|
|
66
|
+
return logging.getLogger("dev_qol_toolkit")
|
|
67
|
+
except Exception:
|
|
68
|
+
# fall back
|
|
69
|
+
pass
|
|
70
|
+
|
|
71
|
+
logger = logging.getLogger("dev_qol_toolkit")
|
|
72
|
+
logger.setLevel(getattr(logging, level.upper(), logging.INFO))
|
|
73
|
+
logger.handlers.clear()
|
|
74
|
+
|
|
75
|
+
fmt = (
|
|
76
|
+
'{"time":"%(asctime)s","level":"%(levelname)s","message":"%(message)s"}'
|
|
77
|
+
if json
|
|
78
|
+
else "%(asctime)s | %(levelname)s | %(message)s"
|
|
79
|
+
)
|
|
80
|
+
formatter = logging.Formatter(fmt)
|
|
81
|
+
|
|
82
|
+
sh = logging.StreamHandler(sys.stderr)
|
|
83
|
+
sh.setFormatter(formatter)
|
|
84
|
+
logger.addHandler(sh)
|
|
85
|
+
|
|
86
|
+
if to_file:
|
|
87
|
+
fh = logging.FileHandler(to_file, encoding="utf-8")
|
|
88
|
+
fh.setFormatter(formatter)
|
|
89
|
+
logger.addHandler(fh)
|
|
90
|
+
|
|
91
|
+
return logger
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@contextmanager
|
|
95
|
+
def log_time(name: str = "block", logger: logging.Logger | None = None):
|
|
96
|
+
"""Context manager to log execution time of a code block.
|
|
97
|
+
|
|
98
|
+
Args:
|
|
99
|
+
name: Name to use in the log message
|
|
100
|
+
logger: Optional logger instance (uses default if None)
|
|
101
|
+
|
|
102
|
+
Examples:
|
|
103
|
+
>>> with log_time("database_query"):
|
|
104
|
+
... # Some database operation
|
|
105
|
+
... time.sleep(0.1)
|
|
106
|
+
# Logs: "database_query took 100.23 ms"
|
|
107
|
+
|
|
108
|
+
>>> import logging
|
|
109
|
+
>>> custom_logger = logging.getLogger("myapp")
|
|
110
|
+
>>> with log_time("api_call", custom_logger):
|
|
111
|
+
... # Some API call
|
|
112
|
+
... pass
|
|
113
|
+
"""
|
|
114
|
+
lg = logger or logging.getLogger("dev_qol_toolkit")
|
|
115
|
+
start = time.perf_counter()
|
|
116
|
+
try:
|
|
117
|
+
yield
|
|
118
|
+
finally:
|
|
119
|
+
dur = (time.perf_counter() - start) * 1000.0
|
|
120
|
+
lg.info("%s took %.2f ms", name, dur)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def log_calls(fn: Callable[..., _T]) -> Callable[..., _T]:
|
|
124
|
+
"""Decorator to log function calls and returns at DEBUG level.
|
|
125
|
+
|
|
126
|
+
Args:
|
|
127
|
+
fn: Function to decorate
|
|
128
|
+
|
|
129
|
+
Returns:
|
|
130
|
+
Decorated function that logs calls and returns
|
|
131
|
+
|
|
132
|
+
Examples:
|
|
133
|
+
>>> @log_calls
|
|
134
|
+
... def add(a: int, b: int) -> int:
|
|
135
|
+
... return a + b
|
|
136
|
+
>>> result = add(2, 3)
|
|
137
|
+
# Logs at DEBUG level:
|
|
138
|
+
# "Calling add args=(2, 3) kwargs={}"
|
|
139
|
+
# "Returned add -> 5"
|
|
140
|
+
|
|
141
|
+
>>> @log_calls
|
|
142
|
+
... def process_data(data: list, **options) -> dict:
|
|
143
|
+
... return {"processed": len(data)}
|
|
144
|
+
>>> result = process_data([1, 2, 3], format="json")
|
|
145
|
+
# Logs function call with arguments and return value
|
|
146
|
+
"""
|
|
147
|
+
import functools
|
|
148
|
+
|
|
149
|
+
logger = logging.getLogger("dev_qol_toolkit")
|
|
150
|
+
|
|
151
|
+
@functools.wraps(fn)
|
|
152
|
+
def wrapper(*args: Any, **kwargs: Any) -> _T:
|
|
153
|
+
logger.debug("Calling %s args=%r kwargs=%r", fn.__name__, args, kwargs)
|
|
154
|
+
result = fn(*args, **kwargs)
|
|
155
|
+
logger.debug("Returned %s -> %r", fn.__name__, result)
|
|
156
|
+
return result
|
|
157
|
+
|
|
158
|
+
return wrapper
|
devtools_py/py.typed
ADDED
|
File without changes
|