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,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
@@ -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