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,288 @@
1
+ """Data manipulation utilities for DevKitX.
2
+
3
+ This module provides utilities for data processing, transformation,
4
+ and manipulation including case conversion, list operations, and
5
+ dictionary utilities.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ from typing import Any
12
+
13
+
14
+ _CAMEL_1 = re.compile(r"(.)([A-Z][a-z]+)")
15
+ _CAMEL_2 = re.compile(r"([a-z0-9])([A-Z])")
16
+
17
+
18
+ def to_snake(name: str) -> str:
19
+ """Convert camelCase or PascalCase to snake_case.
20
+
21
+ Args:
22
+ name: String to convert
23
+
24
+ Returns:
25
+ String in snake_case format
26
+
27
+ Examples:
28
+ >>> to_snake("camelCase")
29
+ 'camel_case'
30
+ >>> to_snake("PascalCase")
31
+ 'pascal_case'
32
+ >>> to_snake("XMLHttpRequest")
33
+ 'xml_http_request'
34
+ """
35
+ s1 = _CAMEL_1.sub(r"\1_\2", name)
36
+ return _CAMEL_2.sub(r"\1_\2", s1).lower()
37
+
38
+
39
+ def to_camel(name: str) -> str:
40
+ """Convert snake_case, kebab-case, or space-separated to camelCase.
41
+
42
+ Args:
43
+ name: String to convert
44
+
45
+ Returns:
46
+ String in camelCase format
47
+
48
+ Examples:
49
+ >>> to_camel("snake_case")
50
+ 'snakeCase'
51
+ >>> to_camel("kebab-case")
52
+ 'kebabCase'
53
+ >>> to_camel("space separated")
54
+ 'spaceSeparated'
55
+ """
56
+ parts = re.split(r"[_\-\s]+", name)
57
+ return parts[0].lower() + "".join(p.capitalize() for p in parts[1:])
58
+
59
+
60
+ def chunk_list(lst: list[Any], size: int) -> list[list[Any]]:
61
+ """Split list into chunks of specified size.
62
+
63
+ Args:
64
+ lst: List to split into chunks
65
+ size: Size of each chunk
66
+
67
+ Returns:
68
+ List of chunks (sublists)
69
+
70
+ Raises:
71
+ ValueError: If size is less than or equal to 0
72
+
73
+ Examples:
74
+ >>> chunk_list([1, 2, 3, 4, 5], 2)
75
+ [[1, 2], [3, 4], [5]]
76
+ >>> chunk_list(['a', 'b', 'c', 'd'], 3)
77
+ [['a', 'b', 'c'], ['d']]
78
+ >>> chunk_list([], 2)
79
+ []
80
+ """
81
+ if size <= 0:
82
+ raise ValueError("size must be > 0")
83
+ return [lst[i : i + size] for i in range(0, len(lst), size)]
84
+
85
+
86
+ def flatten_list(lst: list[list[Any]]) -> list[Any]:
87
+ """Flatten a list of lists into a single list.
88
+
89
+ Args:
90
+ lst: List of lists to flatten
91
+
92
+ Returns:
93
+ Flattened list containing all elements
94
+
95
+ Examples:
96
+ >>> flatten_list([[1, 2], [3, 4], [5]])
97
+ [1, 2, 3, 4, 5]
98
+ >>> flatten_list([['a', 'b'], ['c']])
99
+ ['a', 'b', 'c']
100
+ >>> flatten_list([])
101
+ []
102
+ """
103
+ out: list[Any] = []
104
+ for sub in lst:
105
+ out.extend(sub)
106
+ return out
107
+
108
+
109
+ def deep_get(d: dict, keys: list[str], default: Any = None) -> Any:
110
+ """Get value from nested dictionary using list of keys.
111
+
112
+ Args:
113
+ d: Dictionary to search in
114
+ keys: List of keys representing the path to the value
115
+ default: Default value to return if path doesn't exist
116
+
117
+ Returns:
118
+ Value at the specified path, or default if not found
119
+
120
+ Examples:
121
+ >>> data = {"user": {"profile": {"name": "John"}}}
122
+ >>> deep_get(data, ["user", "profile", "name"])
123
+ 'John'
124
+ >>> deep_get(data, ["user", "settings", "theme"], "default")
125
+ 'default'
126
+ >>> deep_get(data, ["nonexistent"])
127
+ None
128
+ """
129
+ cur: Any = d
130
+ for k in keys:
131
+ if not isinstance(cur, dict) or k not in cur:
132
+ return default
133
+ cur = cur[k]
134
+ return cur
135
+
136
+
137
+ def deep_merge(dict1: dict[str, Any], dict2: dict[str, Any]) -> dict[str, Any]:
138
+ """
139
+ Recursively merge two dictionaries, with dict2 values taking precedence.
140
+
141
+ Args:
142
+ dict1: The base dictionary
143
+ dict2: The dictionary to merge into dict1
144
+
145
+ Returns:
146
+ A new dictionary with merged values
147
+
148
+ Example:
149
+ >>> d1 = {"a": 1, "b": {"c": 2, "d": 3}}
150
+ >>> d2 = {"b": {"c": 4, "e": 5}, "f": 6}
151
+ >>> deep_merge(d1, d2)
152
+ {"a": 1, "b": {"c": 4, "d": 3, "e": 5}, "f": 6}
153
+ """
154
+ result = dict1.copy()
155
+
156
+ for key, value in dict2.items():
157
+ if key in result and isinstance(result[key], dict) and isinstance(value, dict):
158
+ result[key] = deep_merge(result[key], value)
159
+ else:
160
+ result[key] = value
161
+
162
+ return result
163
+
164
+
165
+ def deep_diff(dict1: dict[str, Any], dict2: dict[str, Any]) -> dict[str, Any]:
166
+ """
167
+ Compare two dictionaries and return the differences.
168
+
169
+ Args:
170
+ dict1: The first dictionary
171
+ dict2: The second dictionary
172
+
173
+ Returns:
174
+ A dictionary containing the differences with keys:
175
+ - "added": keys present in dict2 but not dict1
176
+ - "removed": keys present in dict1 but not dict2
177
+ - "modified": keys present in both but with different values
178
+ - "unchanged": keys present in both with same values
179
+
180
+ Example:
181
+ >>> d1 = {"a": 1, "b": 2, "c": {"x": 1}}
182
+ >>> d2 = {"a": 1, "b": 3, "d": 4, "c": {"x": 2}}
183
+ >>> deep_diff(d1, d2)
184
+ {
185
+ "added": {"d": 4},
186
+ "removed": {},
187
+ "modified": {"b": {"old": 2, "new": 3}, "c": {"x": {"old": 1, "new": 2}}},
188
+ "unchanged": {"a": 1}
189
+ }
190
+ """
191
+ added: dict[str, Any] = {}
192
+ removed: dict[str, Any] = {}
193
+ modified: dict[str, Any] = {}
194
+ unchanged: dict[str, Any] = {}
195
+
196
+ # Find keys in dict2 but not in dict1 (added)
197
+ for key in dict2:
198
+ if key not in dict1:
199
+ added[key] = dict2[key]
200
+
201
+ # Find keys in dict1 but not in dict2 (removed)
202
+ for key in dict1:
203
+ if key not in dict2:
204
+ removed[key] = dict1[key]
205
+
206
+ # Compare common keys
207
+ for key in dict1:
208
+ if key in dict2:
209
+ val1, val2 = dict1[key], dict2[key]
210
+
211
+ if isinstance(val1, dict) and isinstance(val2, dict):
212
+ # Recursively diff nested dictionaries
213
+ nested_diff = deep_diff(val1, val2)
214
+ if any(nested_diff[k] for k in ["added", "removed", "modified"]):
215
+ modified[key] = nested_diff
216
+ else:
217
+ unchanged[key] = val1
218
+ elif val1 == val2:
219
+ unchanged[key] = val1
220
+ else:
221
+ modified[key] = {"old": val1, "new": val2}
222
+
223
+ return {"added": added, "removed": removed, "modified": modified, "unchanged": unchanged}
224
+
225
+
226
+ def group_by(items: list[Any], key_func: callable) -> dict[Any, list[Any]]:
227
+ """
228
+ Group items in a list by the result of a key function.
229
+
230
+ Args:
231
+ items: List of items to group
232
+ key_func: Function that takes an item and returns a grouping key
233
+
234
+ Returns:
235
+ Dictionary where keys are the grouping keys and values are lists of items
236
+
237
+ Example:
238
+ >>> items = [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 30}]
239
+ >>> group_by(items, lambda x: x["age"])
240
+ {25: [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 25}], 30: [{"name": "Charlie", "age": 30}]}
241
+ """
242
+ groups: dict[Any, list[Any]] = {}
243
+
244
+ for item in items:
245
+ key = key_func(item)
246
+ if key not in groups:
247
+ groups[key] = []
248
+ groups[key].append(item)
249
+
250
+ return groups
251
+
252
+
253
+ def filter_dict(d: dict[str, Any], predicate: callable) -> dict[str, Any]:
254
+ """
255
+ Filter dictionary items based on a predicate function.
256
+
257
+ Args:
258
+ d: Dictionary to filter
259
+ predicate: Function that takes (key, value) and returns True to keep the item
260
+
261
+ Returns:
262
+ New dictionary containing only items that match the predicate
263
+
264
+ Example:
265
+ >>> data = {"a": 1, "b": 2, "c": 3, "d": 4}
266
+ >>> filter_dict(data, lambda k, v: v > 2)
267
+ {"c": 3, "d": 4}
268
+ """
269
+ return {key: value for key, value in d.items() if predicate(key, value)}
270
+
271
+
272
+ def transform_values(d: dict[str, Any], transformer: callable) -> dict[str, Any]:
273
+ """
274
+ Transform all values in a dictionary using a transformer function.
275
+
276
+ Args:
277
+ d: Dictionary to transform
278
+ transformer: Function that takes a value and returns the transformed value
279
+
280
+ Returns:
281
+ New dictionary with transformed values
282
+
283
+ Example:
284
+ >>> data = {"a": 1, "b": 2, "c": 3}
285
+ >>> transform_values(data, lambda x: x * 2)
286
+ {"a": 2, "b": 4, "c": 6}
287
+ """
288
+ return {key: transformer(value) for key, value in d.items()}
@@ -0,0 +1,393 @@
1
+ """Development and debugging utilities for DevKitX.
2
+
3
+ This module provides utilities for profiling, debugging, testing,
4
+ and development workflow enhancement.
5
+ """
6
+
7
+ import functools
8
+ import json
9
+ import random
10
+ import string
11
+ import threading
12
+ import time
13
+ import tracemalloc
14
+ from datetime import datetime, timedelta
15
+ from http.server import BaseHTTPRequestHandler, HTTPServer
16
+ from typing import Any, Callable, TypeVar
17
+ from urllib.parse import urlparse
18
+
19
+ T = TypeVar("T")
20
+
21
+ __all__ = [
22
+ "time_function",
23
+ "profile_memory",
24
+ "pretty_print_object",
25
+ "generate_test_data",
26
+ "benchmark_functions",
27
+ "MockHTTPServer",
28
+ ]
29
+
30
+
31
+ def time_function(func: Callable[..., T]) -> Callable[..., T]:
32
+ """Decorator to time function execution.
33
+
34
+ Args:
35
+ func: Function to time
36
+
37
+ Returns:
38
+ Decorated function that prints execution time
39
+
40
+ Example:
41
+ >>> @time_function
42
+ ... def slow_function():
43
+ ... time.sleep(0.1)
44
+ ... return "done"
45
+ >>> result = slow_function() # Prints: slow_function took 0.1001s
46
+ >>> result
47
+ 'done'
48
+ """
49
+
50
+ @functools.wraps(func)
51
+ def wrapper(*args: Any, **kwargs: Any) -> T:
52
+ start_time = time.perf_counter()
53
+ try:
54
+ result = func(*args, **kwargs)
55
+ return result
56
+ finally:
57
+ end_time = time.perf_counter()
58
+ execution_time = end_time - start_time
59
+ print(f"{func.__name__} took {execution_time:.4f}s")
60
+
61
+ return wrapper
62
+
63
+
64
+ def profile_memory(func: Callable[..., T]) -> Callable[..., T]:
65
+ """Decorator to profile memory usage of function.
66
+
67
+ Args:
68
+ func: Function to profile
69
+
70
+ Returns:
71
+ Decorated function that prints memory usage
72
+
73
+ Example:
74
+ >>> @profile_memory
75
+ ... def memory_intensive():
76
+ ... data = [i for i in range(10000)]
77
+ ... return len(data)
78
+ >>> result = memory_intensive() # Prints memory usage info
79
+ >>> result
80
+ 10000
81
+ """
82
+
83
+ @functools.wraps(func)
84
+ def wrapper(*args: Any, **kwargs: Any) -> T:
85
+ # Start memory tracing
86
+ tracemalloc.start()
87
+
88
+ try:
89
+ result = func(*args, **kwargs)
90
+ return result
91
+ finally:
92
+ # Get memory usage
93
+ current, peak = tracemalloc.get_traced_memory()
94
+ tracemalloc.stop()
95
+
96
+ # Convert bytes to MB for readability
97
+ current_mb = current / 1024 / 1024
98
+ peak_mb = peak / 1024 / 1024
99
+
100
+ print(
101
+ f"{func.__name__} memory usage - Current: {current_mb:.2f}MB, Peak: {peak_mb:.2f}MB"
102
+ )
103
+
104
+ return wrapper
105
+
106
+
107
+ def pretty_print_object(obj: Any, max_depth: int = 3) -> str:
108
+ """Pretty print object with depth limit.
109
+
110
+ Args:
111
+ obj: Object to print
112
+ max_depth: Maximum depth to traverse
113
+
114
+ Returns:
115
+ Pretty-printed string representation
116
+
117
+ Example:
118
+ >>> data = {"name": "John", "age": 30, "nested": {"city": "NYC"}}
119
+ >>> print(pretty_print_object(data))
120
+ {
121
+ "name": "John",
122
+ "age": 30,
123
+ "nested": {
124
+ "city": "NYC"
125
+ }
126
+ }
127
+ """
128
+
129
+ def _truncate_if_needed(obj: Any, current_depth: int) -> Any:
130
+ """Recursively truncate object if max depth is exceeded."""
131
+ if isinstance(obj, dict):
132
+ if current_depth >= max_depth:
133
+ return f"<dict with {len(obj)} items>"
134
+ return {
135
+ key: _truncate_if_needed(value, current_depth + 1) for key, value in obj.items()
136
+ }
137
+ elif isinstance(obj, list):
138
+ if current_depth >= max_depth:
139
+ return f"<list with {len(obj)} items>"
140
+ return [_truncate_if_needed(item, current_depth + 1) for item in obj]
141
+ elif isinstance(obj, tuple):
142
+ if current_depth >= max_depth:
143
+ return f"<tuple with {len(obj)} items>"
144
+ return tuple(_truncate_if_needed(item, current_depth + 1) for item in obj)
145
+ elif isinstance(obj, set):
146
+ if current_depth >= max_depth:
147
+ return f"<set with {len(obj)} items>"
148
+ return {_truncate_if_needed(item, current_depth + 1) for item in obj}
149
+ else:
150
+ return obj
151
+
152
+ # Truncate the object based on max_depth
153
+ truncated_obj = _truncate_if_needed(obj, 0)
154
+
155
+ # Try to use JSON for pretty printing if possible
156
+ try:
157
+ return json.dumps(truncated_obj, indent=2, default=str, ensure_ascii=False)
158
+ except (TypeError, ValueError):
159
+ # Fallback to repr if JSON serialization fails
160
+ return repr(truncated_obj)
161
+
162
+
163
+ def generate_test_data(schema: dict[str, type], count: int = 10) -> list[dict[str, Any]]:
164
+ """Generate test data based on schema.
165
+
166
+ Args:
167
+ schema: Schema defining data structure and types
168
+ count: Number of test records to generate
169
+
170
+ Returns:
171
+ List of generated test data records
172
+
173
+ Example:
174
+ >>> schema = {"name": str, "age": int, "active": bool}
175
+ >>> data = generate_test_data(schema, count=2)
176
+ >>> len(data)
177
+ 2
178
+ >>> all(isinstance(record["name"], str) for record in data)
179
+ True
180
+ """
181
+
182
+ def _generate_value(data_type: type) -> Any:
183
+ """Generate a random value for the given type."""
184
+ if data_type is str:
185
+ # Generate random string
186
+ length = random.randint(5, 15)
187
+ return "".join(random.choices(string.ascii_letters + string.digits, k=length))
188
+
189
+ elif data_type is int:
190
+ return random.randint(1, 1000)
191
+
192
+ elif data_type is float:
193
+ return round(random.uniform(0.0, 1000.0), 2)
194
+
195
+ elif data_type is bool:
196
+ return random.choice([True, False])
197
+
198
+ elif data_type == datetime:
199
+ # Generate random datetime in the past year
200
+ start_date = datetime(2023, 1, 1)
201
+ end_date = datetime.now()
202
+ time_between = end_date - start_date
203
+ days_between = time_between.days
204
+ random_days = random.randrange(days_between)
205
+ return start_date + timedelta(days=random_days)
206
+
207
+ elif data_type is list:
208
+ # Generate list of random strings
209
+ list_length = random.randint(1, 5)
210
+ return [_generate_value(str) for _ in range(list_length)]
211
+
212
+ elif data_type is dict:
213
+ # Generate simple dict with string keys and values
214
+ dict_size = random.randint(1, 3)
215
+ return {f"key_{i}": _generate_value(str) for i in range(dict_size)}
216
+
217
+ else:
218
+ # For unknown types, return a string representation
219
+ return f"<{data_type.__name__}_value>"
220
+
221
+ # Generate the specified number of records
222
+ test_data = []
223
+ for _ in range(count):
224
+ record = {}
225
+ for field_name, field_type in schema.items():
226
+ record[field_name] = _generate_value(field_type)
227
+ test_data.append(record)
228
+
229
+ return test_data
230
+
231
+
232
+ def benchmark_functions(*funcs: Callable[[], Any], iterations: int = 1000) -> dict[str, float]:
233
+ """Benchmark multiple functions.
234
+
235
+ Args:
236
+ *funcs: Functions to benchmark
237
+ iterations: Number of iterations to run
238
+
239
+ Returns:
240
+ Dictionary mapping function names to average execution times
241
+
242
+ Example:
243
+ >>> def fast_func():
244
+ ... return sum([1, 2, 3])
245
+ >>> def slow_func():
246
+ ... return sum(range(100))
247
+ >>> results = benchmark_functions(fast_func, slow_func, iterations=100)
248
+ >>> len(results)
249
+ 2
250
+ >>> 'fast_func' in results
251
+ True
252
+ """
253
+ results = {}
254
+
255
+ for func in funcs:
256
+ total_time = 0.0
257
+
258
+ # Warm up run
259
+ func()
260
+
261
+ # Benchmark runs
262
+ for _ in range(iterations):
263
+ start_time = time.perf_counter()
264
+ func()
265
+ end_time = time.perf_counter()
266
+ total_time += end_time - start_time
267
+
268
+ # Calculate average time
269
+ average_time = total_time / iterations
270
+ results[func.__name__] = average_time
271
+
272
+ return results
273
+
274
+
275
+ class MockHTTPServer:
276
+ """Mock HTTP server for testing.
277
+
278
+ Example:
279
+ >>> responses = {
280
+ ... "/api/users": {"users": [{"id": 1, "name": "John"}]},
281
+ ... "/api/status": {"status": "ok"}
282
+ ... }
283
+ >>> server = MockHTTPServer(responses)
284
+ >>> url = server.start()
285
+ >>> # Make requests to url + "/api/users"
286
+ >>> server.stop()
287
+ """
288
+
289
+ def __init__(self, responses: dict[str, Any]) -> None:
290
+ """Initialize mock server with predefined responses.
291
+
292
+ Args:
293
+ responses: Dictionary mapping endpoints to responses
294
+ """
295
+ self.responses = responses
296
+ self.server = None
297
+ self.thread = None
298
+ self.port = None
299
+
300
+ def _create_handler(self):
301
+ """Create a request handler class with access to responses."""
302
+ responses = self.responses
303
+
304
+ class MockRequestHandler(BaseHTTPRequestHandler):
305
+ def log_message(self, format, *args):
306
+ # Suppress default logging
307
+ pass
308
+
309
+ def do_GET(self):
310
+ """Handle GET requests."""
311
+ parsed_url = urlparse(self.path)
312
+ path = parsed_url.path
313
+
314
+ if path in responses:
315
+ self.send_response(200)
316
+ self.send_header("Content-type", "application/json")
317
+ self.end_headers()
318
+
319
+ response_data = responses[path]
320
+ if isinstance(response_data, dict):
321
+ response_json = json.dumps(response_data)
322
+ else:
323
+ response_json = str(response_data)
324
+
325
+ self.wfile.write(response_json.encode("utf-8"))
326
+ else:
327
+ self.send_response(404)
328
+ self.send_header("Content-type", "application/json")
329
+ self.end_headers()
330
+ self.wfile.write(b'{"error": "Not found"}')
331
+
332
+ def do_POST(self):
333
+ """Handle POST requests."""
334
+ parsed_url = urlparse(self.path)
335
+ path = parsed_url.path
336
+
337
+ # Read the request body (even if we don't use it)
338
+ content_length = int(self.headers.get("Content-Length", 0))
339
+ if content_length > 0:
340
+ self.rfile.read(content_length)
341
+
342
+ if path in responses:
343
+ self.send_response(200)
344
+ self.send_header("Content-type", "application/json")
345
+ self.end_headers()
346
+
347
+ response_data = responses[path]
348
+ if isinstance(response_data, dict):
349
+ response_json = json.dumps(response_data)
350
+ else:
351
+ response_json = str(response_data)
352
+
353
+ self.wfile.write(response_json.encode("utf-8"))
354
+ else:
355
+ self.send_response(404)
356
+ self.send_header("Content-type", "application/json")
357
+ self.end_headers()
358
+ self.wfile.write(b'{"error": "Not found"}')
359
+
360
+ return MockRequestHandler
361
+
362
+ def start(self) -> str:
363
+ """Start the mock server.
364
+
365
+ Returns:
366
+ Server URL
367
+ """
368
+ if self.server is not None:
369
+ raise RuntimeError("Server is already running")
370
+
371
+ # Find an available port
372
+ self.server = HTTPServer(("localhost", 0), self._create_handler())
373
+ self.port = self.server.server_address[1]
374
+
375
+ # Start server in a separate thread
376
+ self.thread = threading.Thread(target=self.server.serve_forever)
377
+ self.thread.daemon = True
378
+ self.thread.start()
379
+
380
+ return f"http://localhost:{self.port}"
381
+
382
+ def stop(self) -> None:
383
+ """Stop the mock server."""
384
+ if self.server is not None:
385
+ self.server.shutdown()
386
+ self.server.server_close()
387
+ self.server = None
388
+
389
+ if self.thread is not None:
390
+ self.thread.join(timeout=1.0)
391
+ self.thread = None
392
+
393
+ self.port = None