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,557 @@
1
+ """Configuration management utilities for DevKitX.
2
+
3
+ This module provides utilities for loading, managing, and validating
4
+ configuration from various sources including JSON, YAML, TOML, and .env files.
5
+ """
6
+
7
+ import json
8
+ import os
9
+ import re
10
+ from pathlib import Path
11
+ from typing import Any, TypeVar
12
+
13
+ T = TypeVar("T")
14
+
15
+ __all__ = [
16
+ "ConfigManager",
17
+ "load_dotenv",
18
+ "load_yaml_config",
19
+ "load_toml_config",
20
+ ]
21
+
22
+
23
+ class ConfigManager:
24
+ """Configuration manager for handling multiple config sources."""
25
+
26
+ def __init__(self, config_paths: list[str | Path]) -> None:
27
+ """Initialize ConfigManager with config file paths.
28
+
29
+ Args:
30
+ config_paths: List of configuration file paths
31
+ """
32
+ self.config_paths = [Path(p) for p in config_paths]
33
+ self._config: dict[str, Any] = {}
34
+ self._loaded = False
35
+
36
+ def load(self) -> dict[str, Any]:
37
+ """Load configuration from all sources.
38
+
39
+ Returns:
40
+ Merged configuration dictionary
41
+
42
+ Raises:
43
+ ValueError: If no valid configuration files are found
44
+ """
45
+ self._config = {}
46
+ loaded_any = False
47
+
48
+ for config_path in self.config_paths:
49
+ if not config_path.exists():
50
+ continue
51
+
52
+ try:
53
+ if config_path.suffix.lower() in [".env"]:
54
+ config_data = load_dotenv(config_path)
55
+ elif config_path.suffix.lower() in [".yaml", ".yml"]:
56
+ config_data = load_yaml_config(config_path)
57
+ elif config_path.suffix.lower() in [".toml"]:
58
+ config_data = load_toml_config(config_path)
59
+ elif config_path.suffix.lower() in [".json"]:
60
+ with open(config_path, "r", encoding="utf-8") as f:
61
+ config_data = json.load(f)
62
+ else:
63
+ # Try to detect format by content
64
+ config_data = self._auto_detect_format(config_path)
65
+
66
+ # Merge configuration data
67
+ self._deep_merge(self._config, config_data)
68
+ loaded_any = True
69
+
70
+ except Exception as e:
71
+ # Log warning but continue with other files
72
+ print(f"Warning: Failed to load config from {config_path}: {e}")
73
+ continue
74
+
75
+ if not loaded_any and self.config_paths:
76
+ raise ValueError("No valid configuration files could be loaded")
77
+
78
+ self._loaded = True
79
+ return self._config.copy()
80
+
81
+ def get(self, key: str, default: Any = None, type_hint: type[T] | None = None) -> T:
82
+ """Get configuration value with optional type casting.
83
+
84
+ Args:
85
+ key: Configuration key (supports dot notation for nested keys)
86
+ default: Default value if key not found
87
+ type_hint: Type to cast the value to
88
+
89
+ Returns:
90
+ Configuration value
91
+ """
92
+ if not self._loaded:
93
+ self.load()
94
+
95
+ # Support dot notation for nested keys
96
+ value = self._config
97
+ for key_part in key.split("."):
98
+ if isinstance(value, dict) and key_part in value:
99
+ value = value[key_part]
100
+ else:
101
+ value = default
102
+ break
103
+
104
+ # Type casting if requested
105
+ if type_hint is not None and value is not default:
106
+ try:
107
+ if type_hint is bool:
108
+ # Handle string boolean values
109
+ if isinstance(value, str):
110
+ return value.lower() in ("true", "1", "yes", "on") # type: ignore
111
+ return bool(value) # type: ignore
112
+ elif type_hint in (int, float, str):
113
+ return type_hint(value) # type: ignore
114
+ else:
115
+ return value # type: ignore
116
+ except (ValueError, TypeError):
117
+ return default # type: ignore
118
+
119
+ return value # type: ignore
120
+
121
+ def set(self, key: str, value: Any) -> None:
122
+ """Set configuration value.
123
+
124
+ Args:
125
+ key: Configuration key (supports dot notation for nested keys)
126
+ value: Value to set
127
+ """
128
+ if not self._loaded:
129
+ self.load()
130
+
131
+ # Support dot notation for nested keys
132
+ config = self._config
133
+ key_parts = key.split(".")
134
+
135
+ # Navigate to the parent of the target key
136
+ for key_part in key_parts[:-1]:
137
+ if key_part not in config:
138
+ config[key_part] = {}
139
+ elif not isinstance(config[key_part], dict):
140
+ config[key_part] = {}
141
+ config = config[key_part]
142
+
143
+ # Set the final value
144
+ config[key_parts[-1]] = value
145
+
146
+ def save(self, path: str | Path | None = None) -> None:
147
+ """Save configuration to file.
148
+
149
+ Args:
150
+ path: Optional path to save to, uses first config path if None
151
+
152
+ Raises:
153
+ ValueError: If no path is provided and no config paths are available
154
+ """
155
+ if not self._loaded:
156
+ self.load()
157
+
158
+ if path is None:
159
+ if not self.config_paths:
160
+ raise ValueError("No path provided and no config paths available")
161
+ save_path = self.config_paths[0]
162
+ else:
163
+ save_path = Path(path)
164
+
165
+ # Determine format from file extension
166
+ if save_path.suffix.lower() in [".json"]:
167
+ with open(save_path, "w", encoding="utf-8") as f:
168
+ json.dump(self._config, f, indent=2)
169
+ elif save_path.suffix.lower() in [".yaml", ".yml"]:
170
+ self._save_as_yaml(save_path)
171
+ elif save_path.suffix.lower() in [".toml"]:
172
+ self._save_as_toml(save_path)
173
+ elif save_path.suffix.lower() in [".env"]:
174
+ self._save_as_env(save_path)
175
+ else:
176
+ # Default to JSON
177
+ with open(save_path, "w", encoding="utf-8") as f:
178
+ json.dump(self._config, f, indent=2)
179
+
180
+ def merge_env_vars(self, prefix: str = "") -> None:
181
+ """Merge environment variables into configuration.
182
+
183
+ Args:
184
+ prefix: Prefix for environment variables to include
185
+ """
186
+ if not self._loaded:
187
+ self.load()
188
+
189
+ for key, value in os.environ.items():
190
+ if prefix and not key.startswith(prefix):
191
+ continue
192
+
193
+ # Remove prefix if specified
194
+ config_key = key[len(prefix) :] if prefix else key
195
+
196
+ # Convert environment variable name to config key
197
+ # e.g., MY_APP_DATABASE_URL -> my_app.database.url
198
+ config_key = config_key.lower().replace("_", ".")
199
+
200
+ # Set the value using dot notation
201
+ self.set(config_key, value)
202
+
203
+ def _deep_merge(self, target: dict[str, Any], source: dict[str, Any]) -> None:
204
+ """Deep merge source dictionary into target dictionary."""
205
+ for key, value in source.items():
206
+ if key in target and isinstance(target[key], dict) and isinstance(value, dict):
207
+ self._deep_merge(target[key], value)
208
+ else:
209
+ target[key] = value
210
+
211
+ def _auto_detect_format(self, path: Path) -> dict[str, Any]:
212
+ """Auto-detect configuration file format by content."""
213
+ with open(path, "r", encoding="utf-8") as f:
214
+ content = f.read().strip()
215
+
216
+ # Try JSON first
217
+ try:
218
+ return json.loads(content)
219
+ except json.JSONDecodeError:
220
+ pass
221
+
222
+ # Try YAML
223
+ if ":" in content:
224
+ try:
225
+ return _parse_simple_yaml(path)
226
+ except Exception:
227
+ pass
228
+
229
+ # Try TOML
230
+ if "=" in content:
231
+ try:
232
+ return _parse_simple_toml(path)
233
+ except Exception:
234
+ pass
235
+
236
+ # Try .env format
237
+ try:
238
+ return load_dotenv(path)
239
+ except Exception:
240
+ pass
241
+
242
+ raise ValueError(f"Could not determine format for {path}")
243
+
244
+ def _save_as_yaml(self, path: Path) -> None:
245
+ """Save configuration as YAML format."""
246
+ try:
247
+ import yaml
248
+
249
+ with open(path, "w", encoding="utf-8") as f:
250
+ yaml.dump(self._config, f, default_flow_style=False)
251
+ except ImportError:
252
+ # Fallback to simple YAML format
253
+ with open(path, "w", encoding="utf-8") as f:
254
+ self._write_simple_yaml(f, self._config)
255
+
256
+ def _save_as_toml(self, path: Path) -> None:
257
+ """Save configuration as TOML format."""
258
+ try:
259
+ import tomli_w
260
+
261
+ with open(path, "wb") as f:
262
+ tomli_w.dump(self._config, f)
263
+ except ImportError:
264
+ # Fallback to simple TOML format
265
+ with open(path, "w", encoding="utf-8") as f:
266
+ self._write_simple_toml(f, self._config)
267
+
268
+ def _save_as_env(self, path: Path) -> None:
269
+ """Save configuration as .env format."""
270
+ with open(path, "w", encoding="utf-8") as f:
271
+ self._write_env_format(f, self._config)
272
+
273
+ def _write_simple_yaml(self, f, data: dict[str, Any], indent: int = 0) -> None:
274
+ """Write simple YAML format."""
275
+ for key, value in data.items():
276
+ if isinstance(value, dict):
277
+ f.write(f"{' ' * indent}{key}:\n")
278
+ self._write_simple_yaml(f, value, indent + 1)
279
+ else:
280
+ f.write(f"{' ' * indent}{key}: {self._yaml_value(value)}\n")
281
+
282
+ def _write_simple_toml(self, f, data: dict[str, Any]) -> None:
283
+ """Write simple TOML format."""
284
+ # Write top-level keys first
285
+ for key, value in data.items():
286
+ if not isinstance(value, dict):
287
+ f.write(f"{key} = {self._toml_value(value)}\n")
288
+
289
+ # Write sections
290
+ for key, value in data.items():
291
+ if isinstance(value, dict):
292
+ f.write(f"\n[{key}]\n")
293
+ for sub_key, sub_value in value.items():
294
+ f.write(f"{sub_key} = {self._toml_value(sub_value)}\n")
295
+
296
+ def _write_env_format(self, f, data: dict[str, Any], prefix: str = "") -> None:
297
+ """Write .env format."""
298
+ for key, value in data.items():
299
+ if isinstance(value, dict):
300
+ new_prefix = f"{prefix}{key.upper()}_" if prefix else f"{key.upper()}_"
301
+ self._write_env_format(f, value, new_prefix)
302
+ else:
303
+ env_key = f"{prefix}{key.upper()}"
304
+ f.write(f"{env_key}={value}\n")
305
+
306
+ def _yaml_value(self, value: Any) -> str:
307
+ """Format value for YAML output."""
308
+ if isinstance(value, bool):
309
+ return "true" if value else "false"
310
+ elif isinstance(value, str):
311
+ return f"'{value}'"
312
+ else:
313
+ return str(value)
314
+
315
+ def _toml_value(self, value: Any) -> str:
316
+ """Format value for TOML output."""
317
+ if isinstance(value, bool):
318
+ return "true" if value else "false"
319
+ elif isinstance(value, str):
320
+ return f"'{value}'"
321
+ else:
322
+ return str(value)
323
+
324
+
325
+ def load_dotenv(path: str | Path) -> dict[str, str]:
326
+ """Load environment variables from .env file.
327
+
328
+ Args:
329
+ path: Path to .env file
330
+
331
+ Returns:
332
+ Dictionary of environment variables
333
+
334
+ Raises:
335
+ FileNotFoundError: If the .env file doesn't exist
336
+ ValueError: If the .env file contains invalid syntax
337
+ """
338
+ env_path = Path(path)
339
+ if not env_path.exists():
340
+ raise FileNotFoundError(f"Environment file not found: {env_path}")
341
+
342
+ env_vars = {}
343
+
344
+ with open(env_path, "r", encoding="utf-8") as f:
345
+ for line_num, line in enumerate(f, 1):
346
+ line = line.strip()
347
+
348
+ # Skip empty lines and comments
349
+ if not line or line.startswith("#"):
350
+ continue
351
+
352
+ # Match KEY=VALUE pattern
353
+ match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$", line)
354
+ if not match:
355
+ raise ValueError(f"Invalid syntax in {env_path} at line {line_num}: {line}")
356
+
357
+ key, value = match.groups()
358
+
359
+ # Handle quoted values
360
+ if value.startswith('"') and value.endswith('"'):
361
+ value = value[1:-1]
362
+ elif value.startswith("'") and value.endswith("'"):
363
+ value = value[1:-1]
364
+
365
+ env_vars[key] = value
366
+
367
+ return env_vars
368
+
369
+
370
+ def load_yaml_config(path: str | Path) -> dict[str, Any]:
371
+ """Load configuration from YAML file.
372
+
373
+ Note: This is a basic YAML parser that handles simple cases.
374
+ For complex YAML files, consider using the 'pyyaml' library.
375
+
376
+ Args:
377
+ path: Path to YAML file
378
+
379
+ Returns:
380
+ Configuration dictionary
381
+
382
+ Raises:
383
+ FileNotFoundError: If the YAML file doesn't exist
384
+ ValueError: If the YAML file contains invalid syntax
385
+ """
386
+ yaml_path = Path(path)
387
+ if not yaml_path.exists():
388
+ raise FileNotFoundError(f"YAML file not found: {yaml_path}")
389
+
390
+ try:
391
+ # Try to import yaml first
392
+ import yaml
393
+
394
+ with open(yaml_path, "r", encoding="utf-8") as f:
395
+ return yaml.safe_load(f) or {}
396
+ except ImportError:
397
+ # Fallback to basic YAML parsing for simple cases
398
+ return _parse_simple_yaml(yaml_path)
399
+
400
+
401
+ def load_toml_config(path: str | Path) -> dict[str, Any]:
402
+ """Load configuration from TOML file.
403
+
404
+ Args:
405
+ path: Path to TOML file
406
+
407
+ Returns:
408
+ Configuration dictionary
409
+
410
+ Raises:
411
+ FileNotFoundError: If the TOML file doesn't exist
412
+ ValueError: If the TOML file contains invalid syntax
413
+ """
414
+ toml_path = Path(path)
415
+ if not toml_path.exists():
416
+ raise FileNotFoundError(f"TOML file not found: {toml_path}")
417
+
418
+ try:
419
+ # Try to use tomllib (Python 3.11+) or tomli
420
+ try:
421
+ import tomllib
422
+
423
+ with open(toml_path, "rb") as f:
424
+ return tomllib.load(f)
425
+ except ImportError:
426
+ import tomli
427
+
428
+ with open(toml_path, "rb") as f:
429
+ return tomli.load(f)
430
+ except ImportError:
431
+ # Fallback to basic TOML parsing for simple cases
432
+ return _parse_simple_toml(toml_path)
433
+
434
+
435
+ def _parse_simple_yaml(path: Path) -> dict[str, Any]:
436
+ """Basic YAML parser for simple key-value pairs and lists.
437
+
438
+ This is a fallback parser that handles basic YAML syntax.
439
+ For complex YAML files, install the 'pyyaml' library.
440
+ """
441
+ config = {}
442
+ current_section = config
443
+
444
+ with open(path, "r", encoding="utf-8") as f:
445
+ for line_num, line in enumerate(f, 1):
446
+ line = line.rstrip()
447
+
448
+ # Skip empty lines and comments
449
+ if not line or line.strip().startswith("#"):
450
+ continue
451
+
452
+ # Handle simple key-value pairs
453
+ if ":" in line and not line.startswith(" "):
454
+ key, value = line.split(":", 1)
455
+ key = key.strip()
456
+ value = value.strip()
457
+
458
+ if value:
459
+ current_section[key] = _parse_yaml_value(value)
460
+ else:
461
+ # This might be a section header
462
+ current_section[key] = {}
463
+
464
+ return config
465
+
466
+
467
+ def _parse_simple_toml(path: Path) -> dict[str, Any]:
468
+ """Basic TOML parser for simple key-value pairs and sections.
469
+
470
+ This is a fallback parser that handles basic TOML syntax.
471
+ For complex TOML files, install the 'tomli' library.
472
+ """
473
+ config = {}
474
+ current_section = config
475
+
476
+ with open(path, "r", encoding="utf-8") as f:
477
+ for line_num, line in enumerate(f, 1):
478
+ line = line.strip()
479
+
480
+ # Skip empty lines and comments
481
+ if not line or line.startswith("#"):
482
+ continue
483
+
484
+ # Handle section headers [section]
485
+ if line.startswith("[") and line.endswith("]"):
486
+ section_name = line[1:-1]
487
+ current_section = config.setdefault(section_name, {})
488
+ continue
489
+
490
+ # Handle key-value pairs
491
+ if "=" in line:
492
+ key, value = line.split("=", 1)
493
+ key = key.strip()
494
+ value = value.strip()
495
+ current_section[key] = _parse_toml_value(value)
496
+
497
+ return config
498
+
499
+
500
+ def _parse_yaml_value(value: str) -> Any:
501
+ """Parse a YAML value string into appropriate Python type."""
502
+ value = value.strip()
503
+
504
+ # Handle quoted strings
505
+ if (value.startswith('"') and value.endswith('"')) or (
506
+ value.startswith("'") and value.endswith("'")
507
+ ):
508
+ return value[1:-1]
509
+
510
+ # Handle booleans
511
+ if value.lower() in ("true", "yes", "on"):
512
+ return True
513
+ if value.lower() in ("false", "no", "off"):
514
+ return False
515
+
516
+ # Handle null
517
+ if value.lower() in ("null", "none", "~", ""):
518
+ return None
519
+
520
+ # Try to parse as number
521
+ try:
522
+ if "." in value:
523
+ return float(value)
524
+ return int(value)
525
+ except ValueError:
526
+ pass
527
+
528
+ # Return as string
529
+ return value
530
+
531
+
532
+ def _parse_toml_value(value: str) -> Any:
533
+ """Parse a TOML value string into appropriate Python type."""
534
+ value = value.strip()
535
+
536
+ # Handle quoted strings
537
+ if (value.startswith('"') and value.endswith('"')) or (
538
+ value.startswith("'") and value.endswith("'")
539
+ ):
540
+ return value[1:-1]
541
+
542
+ # Handle booleans
543
+ if value.lower() == "true":
544
+ return True
545
+ if value.lower() == "false":
546
+ return False
547
+
548
+ # Try to parse as number
549
+ try:
550
+ if "." in value:
551
+ return float(value)
552
+ return int(value)
553
+ except ValueError:
554
+ pass
555
+
556
+ # Return as string
557
+ return value