oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/config/defaults.py

@@ -0,0 +1,254 @@
+"""Default configuration values and injection.
+
+This module provides default configuration values and utilities
+for injecting defaults into user configurations.
+
+
+Example:
+    >>> from oscura.config.defaults import inject_defaults
+    >>> config = {"name": "test"}
+    >>> full_config = inject_defaults(config, "protocol")
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+# Default configuration values
+DEFAULT_CONFIG: dict[str, Any] = {
+    "version": "1.0",
+    "defaults": {
+        "sample_rate": 1e6,  # 1 MHz default
+        "window_function": "hann",
+        "fft_size": 1024,
+    },
+    "loaders": {
+        "auto_detect": True,
+        "formats": ["wfm", "csv", "npz", "hdf5", "tdms", "vcd", "sr", "wav", "pcap"],
+        "tektronix": {"byte_order": "little"},
+        "csv": {"delimiter": ",", "skip_header": 0},
+    },
+    "measurements": {
+        "rise_time": {"ref_levels": [0.1, 0.9]},
+        "fall_time": {"ref_levels": [0.9, 0.1]},
+        "frequency": {"min_periods": 3},
+    },
+    "spectral": {
+        "default_window": "hann",
+        "overlap": 0.5,
+        "nfft": None,  # Auto-determine from signal length
+    },
+    "visualization": {
+        "default_style": "seaborn",
+        "figure_size": [10, 6],
+        "dpi": 100,
+        "colormap": "viridis",
+    },
+    "export": {
+        "csv": {"precision": 6},
+        "hdf5": {"compression": "gzip", "compression_opts": 4},
+    },
+    "logging": {
+        "level": "INFO",
+        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    },
+}
+
+
+# Schema-specific default values
+SCHEMA_DEFAULTS: dict[str, dict[str, Any]] = {
+    "protocol": {
+        "version": "1.0.0",
+        "timing": {
+            "data_bits": [8],
+            "stop_bits": [1],
+            "parity": ["none"],
+        },
+    },
+    "pipeline": {
+        "version": "1.0.0",
+        "parallel_groups": [],
+    },
+    "logic_family": {
+        "temperature_range": {
+            "min": 0,
+            "max": 70,
+        },
+    },
+    "threshold_profile": {
+        "tolerance": 0,
+        "overrides": {},
+    },
+    "preferences": {
+        "defaults": {
+            "sample_rate": 1e6,
+            "window_function": "hann",
+        },
+        "visualization": {
+            "style": "seaborn",
+            "dpi": 100,
+        },
+        "export": {
+            "default_format": "csv",
+            "precision": 6,
+        },
+        "logging": {
+            "level": "INFO",
+        },
+    },
+}
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge two dictionaries.
+
+    Values from override take precedence. Nested dictionaries are
+    merged recursively.
+
+    Args:
+        base: Base dictionary.
+        override: Dictionary with values to override.
+
+    Returns:
+        Merged dictionary (new instance).
+
+    Example:
+        >>> base = {"a": 1, "b": {"c": 2}}
+        >>> override = {"b": {"d": 3}}
+        >>> deep_merge(base, override)
+        {'a': 1, 'b': {'c': 2, 'd': 3}}
+    """
+    result = copy.deepcopy(base)
+
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+
+    return result
+
+
+def inject_defaults(
+    config: dict[str, Any],
+    schema_name: str,
+) -> dict[str, Any]:
+    """Inject default values into configuration.
+
+    Adds default values for missing fields based on schema type.
+
+    Args:
+        config: User configuration dictionary.
+        schema_name: Schema name to determine defaults.
+
+    Returns:
+        Configuration with defaults injected.
+
+    Example:
+        >>> config = {"name": "uart", "timing": {"baud_rates": [9600]}}
+        >>> full = inject_defaults(config, "protocol")
+        >>> print(full["timing"]["data_bits"])
+        [8]
+    """
+    defaults = SCHEMA_DEFAULTS.get(schema_name, {})
+
+    if not defaults:
+        return copy.deepcopy(config)
+
+    # Merge defaults with config (config takes precedence)
+    return deep_merge(defaults, config)
+
+
+def get_effective_config(
+    user_config: dict[str, Any] | None = None,
+    schema_name: str | None = None,
+) -> dict[str, Any]:
+    """Get effective configuration with all defaults applied.
+
+    Combines base defaults, schema-specific defaults, and user configuration.
+
+    Args:
+        user_config: User-provided configuration.
+        schema_name: Schema to apply defaults for.
+
+    Returns:
+        Complete configuration with all defaults.
+
+    Example:
+        >>> config = get_effective_config({"defaults": {"sample_rate": 2e6}})
+        >>> print(config["defaults"]["sample_rate"])
+        2000000.0
+    """
+    # Start with base defaults
+    result = copy.deepcopy(DEFAULT_CONFIG)
+
+    # Add schema-specific defaults
+    if schema_name and schema_name in SCHEMA_DEFAULTS:
+        schema_defaults = SCHEMA_DEFAULTS[schema_name]
+        result = deep_merge(result, schema_defaults)
+
+    # Apply user configuration
+    if user_config:
+        result = deep_merge(result, user_config)
+
+    return result
+
+
+def get_default(
+    key_path: str,
+    schema_name: str | None = None,
+) -> Any:
+    """Get default value for a configuration key.
+
+    Args:
+        key_path: Dot-separated path (e.g., "defaults.sample_rate").
+        schema_name: Optional schema for schema-specific defaults.
+
+    Returns:
+        Default value or None if not found.
+
+    Example:
+        >>> get_default("defaults.sample_rate")
+        1000000.0
+    """
+    # Check schema-specific defaults first
+    if schema_name and schema_name in SCHEMA_DEFAULTS:
+        value = _get_nested(SCHEMA_DEFAULTS[schema_name], key_path)
+        if value is not None:
+            return value
+
+    # Fall back to base defaults
+    return _get_nested(DEFAULT_CONFIG, key_path)
+
+
+def _get_nested(config: dict[str, Any], key_path: str) -> Any:
+    """Get nested value by dot-separated path.
+
+    Args:
+        config: Configuration dictionary.
+        key_path: Dot-separated path.
+
+    Returns:
+        Value or None if not found.
+    """
+    keys = key_path.split(".")
+    value = config
+
+    for key in keys:
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        else:
+            return None
+
+    return value
+
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "SCHEMA_DEFAULTS",
+    "deep_merge",
+    "get_default",
+    "get_effective_config",
+    "inject_defaults",
+]

oscura/config/loader.py

@@ -0,0 +1,348 @@
+"""Configuration file loading utilities.
+
+This module provides unified configuration loading from YAML and JSON files
+with support for schema validation, default injection, and path resolution.
+
+
+Example:
+    >>> from oscura.config.loader import load_config_file
+    >>> config = load_config_file("pipeline.yaml", schema="pipeline")
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from oscura.core.exceptions import ConfigurationError
+
+# Try to import yaml
+try:
+    import yaml
+
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
+
+
+def load_config_file(
+    path: str | Path,
+    *,
+    schema: str | None = None,
+    validate: bool = True,
+    inject_defaults: bool = True,
+) -> dict[str, Any]:
+    """Load configuration from YAML or JSON file.
+
+    Automatically detects file format from extension.
+    Optionally validates against schema and injects defaults.
+
+    Args:
+        path: Path to configuration file.
+        schema: Schema name to validate against (e.g., "protocol").
+        validate: If True and schema provided, validate configuration.
+        inject_defaults: If True, inject default values from schema.
+
+    Returns:
+        Configuration dictionary.
+
+    Raises:
+        ConfigurationError: If file cannot be loaded or parsed.
+
+    Example:
+        >>> config = load_config_file("uart.yaml", schema="protocol")
+        >>> print(config["name"])
+        'uart'
+    """
+    path = Path(path).expanduser().resolve()
+
+    if not path.exists():
+        raise ConfigurationError(
+            "Configuration file not found",
+            config_key=str(path),
+        )
+
+    # Determine format from extension
+    ext = path.suffix.lower()
+
+    if ext in (".yaml", ".yml"):
+        config = _load_yaml(path)
+    elif ext == ".json":
+        config = _load_json(path)
+    else:
+        # Try YAML first, then JSON
+        try:
+            config = _load_yaml(path)
+        except ConfigurationError:
+            try:
+                config = _load_json(path)
+            except ConfigurationError:
+                raise ConfigurationError(  # noqa: B904
+                    f"Unsupported configuration format: {ext}",
+                    config_key=str(path),
+                    fix_hint="Use .yaml, .yml, or .json extension",
+                )
+
+    # Validate against schema if requested
+    if validate and schema is not None:
+        from oscura.config.schema import validate_against_schema
+
+        validate_against_schema(config, schema)
+
+    # Inject defaults if requested
+    if inject_defaults and schema is not None:
+        from oscura.config.defaults import inject_defaults as do_inject
+
+        config = do_inject(config, schema)
+
+    return config
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    """Load YAML configuration file.
+
+    Args:
+        path: Path to YAML file.
+
+    Returns:
+        Parsed configuration dictionary.
+
+    Raises:
+        ConfigurationError: If YAML parsing fails.
+    """
+    if not YAML_AVAILABLE:
+        raise ConfigurationError(
+            "YAML support not available",
+            fix_hint="Install PyYAML: pip install pyyaml",
+        )
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = yaml.safe_load(f)
+
+        if content is None:
+            return {}
+
+        if not isinstance(content, dict):
+            raise ConfigurationError(
+                "Configuration must be a dictionary",
+                config_key=str(path),
+                expected_type="object",
+                actual_value=type(content).__name__,
+            )
+
+        return content
+
+    except yaml.YAMLError as e:
+        # Extract line number from YAML error
+        line = None
+        if hasattr(e, "problem_mark") and e.problem_mark is not None:
+            line = e.problem_mark.line + 1
+
+        raise ConfigurationError(
+            "Failed to parse YAML configuration",
+            config_key=str(path),
+            details=f"Line {line}: {e}" if line else str(e),
+        ) from e
+    except OSError as e:
+        raise ConfigurationError(
+            "Failed to read configuration file",
+            config_key=str(path),
+            details=str(e),
+        ) from e
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    """Load JSON configuration file.
+
+    Args:
+        path: Path to JSON file.
+
+    Returns:
+        Parsed configuration dictionary.
+
+    Raises:
+        ConfigurationError: If JSON parsing fails.
+    """
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = json.load(f)
+
+        if content is None:
+            return {}
+
+        if not isinstance(content, dict):
+            raise ConfigurationError(
+                "Configuration must be a dictionary",
+                config_key=str(path),
+                expected_type="object",
+                actual_value=type(content).__name__,
+            )
+
+        return content
+
+    except json.JSONDecodeError as e:
+        raise ConfigurationError(
+            "Failed to parse JSON configuration",
+            config_key=str(path),
+            details=f"Line {e.lineno}, column {e.colno}: {e.msg}",
+        ) from e
+    except OSError as e:
+        raise ConfigurationError(
+            "Failed to read configuration file",
+            config_key=str(path),
+            details=str(e),
+        ) from e
+
+
+def load_config(
+    config_path: str | Path | None = None,
+    *,
+    use_defaults: bool = True,
+) -> dict[str, Any]:
+    """Load TraceKit configuration.
+
+    Searches for configuration in standard locations if no path provided.
+
+    Args:
+        config_path: Path to configuration file. If None, searches
+            standard locations.
+        use_defaults: If True, merge with default configuration.
+
+    Returns:
+        Configuration dictionary.
+
+    Example:
+        >>> config = load_config()  # Auto-find config
+        >>> config = load_config("~/.oscura/config.yaml")
+    """
+    from oscura.config.defaults import DEFAULT_CONFIG, deep_merge
+
+    config: dict[str, Any] = {}
+
+    if use_defaults:
+        import copy
+
+        config = copy.deepcopy(DEFAULT_CONFIG)
+
+    if config_path is None:
+        # Search standard locations
+        search_paths = [
+            Path.cwd() / "oscura.yaml",
+            Path.cwd() / ".oscura.yaml",
+            Path.cwd() / "oscura.json",
+            Path.home() / ".oscura" / "config.yaml",
+            Path.home() / ".config" / "oscura" / "config.yaml",
+        ]
+
+        for path in search_paths:
+            if path.exists():
+                config_path = path
+                break
+
+    if config_path is not None:
+        user_config = load_config_file(
+            config_path,
+            validate=False,
+            inject_defaults=False,
+        )
+        config = deep_merge(config, user_config) if use_defaults else user_config
+
+    return config
+
+
+def save_config(
+    config: dict[str, Any],
+    path: str | Path,
+    *,
+    format: str | None = None,
+) -> None:
+    """Save configuration to file.
+
+    Args:
+        config: Configuration dictionary to save.
+        path: Output file path.
+        format: Output format ("yaml" or "json"). Auto-detected from
+            extension if not specified.
+
+    Raises:
+        ConfigurationError: If configuration cannot be saved.
+
+    Example:
+        >>> save_config(config, "config.yaml")
+        >>> save_config(config, "config.json")
+    """
+    path = Path(path).expanduser().resolve()
+
+    # Determine format
+    if format is None:
+        ext = path.suffix.lower()
+        if ext in (".yaml", ".yml"):
+            format = "yaml"
+        elif ext == ".json":
+            format = "json"
+        else:
+            format = "yaml"  # Default
+
+    # Create parent directory
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if format == "yaml":
+            if not YAML_AVAILABLE:
+                raise ConfigurationError(
+                    "YAML support not available",
+                    fix_hint="Install PyYAML: pip install pyyaml",
+                )
+            with open(path, "w", encoding="utf-8") as f:
+                yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+        else:
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(config, f, indent=2)
+
+    except OSError as e:
+        raise ConfigurationError(
+            "Failed to save configuration",
+            config_key=str(path),
+            details=str(e),
+        ) from e
+
+
+def get_config_value(
+    config: dict[str, Any],
+    key_path: str,
+    default: Any = None,
+) -> Any:
+    """Get configuration value by dot-separated path.
+
+    Args:
+        config: Configuration dictionary.
+        key_path: Dot-separated path (e.g., "defaults.sample_rate").
+        default: Default value if key not found.
+
+    Returns:
+        Configuration value or default.
+
+    Example:
+        >>> get_config_value(config, "defaults.sample_rate", 1e6)
+        1000000.0
+    """
+    keys = key_path.split(".")
+    value = config
+
+    for key in keys:
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        else:
+            return default
+
+    return value
+
+
+__all__ = [
+    "get_config_value",
+    "load_config",
+    "load_config_file",
+    "save_config",
+]