Configuration Layer¶

def __new__(cls, config_file: Optional[Path] = None):
    """
    Singleton implementation.

    Parameters
    ----------
    config_file : Optional[Path], default=None
        Path to config file. Only used on first instantiation.
    """
    if cls._instance is None:
        cls._instance = super(Settings, cls).__new__(cls)
        cls._instance._initialized = False
    return cls._instance

def get(self, key: str, default: Any = None) -> Any:
    """
    Get setting value by dot-notation key.

    Parameters
    ----------
    key : str
        Setting key in dot notation (e.g., 'cache.max_size')
    default : Any, default=None
        Default value if key not found

    Returns
    -------
    Any
        Setting value or default
    """
    keys = key.split(".")
    value = self._settings

    for k in keys:
        if isinstance(value, dict) and k in value:
            value = value[k]
        else:
            return default

    return value

def set(self, key: str, value: Any) -> None:
    """
    Set setting value by dot-notation key.

    Parameters
    ----------
    key : str
        Setting key in dot notation
    value : Any
        Value to set
    """
    keys = key.split(".")
    settings = self._settings

    # Navigate to nested dict
    for k in keys[:-1]:
        if k not in settings:
            settings[k] = {}
        settings = settings[k]

    # Set value
    settings[keys[-1]] = value

    logger.debug(f"Setting updated: {key} = {value}")

def get_section(self, section: str) -> Dict[str, Any]:
    """
    Get entire settings section.

    Parameters
    ----------
    section : str
        Section name (e.g., 'cache')

    Returns
    -------
    Dict[str, Any]
        Section dictionary or empty dict if not found
    """
    return self._settings.get(section, {})

def reload(self) -> None:
    """Reload settings from file."""
    logger.info("Reloading settings")
    self._load_settings()

def save(self, output_file: Optional[Path] = None) -> None:
    """
    Save current settings to YAML file.

    Parameters
    ----------
    output_file : Optional[Path], default=None
        Output file path. If None, uses original config_file.
    """
    output_file = output_file or self.config_file

    try:
        output_file.parent.mkdir(parents=True, exist_ok=True)

        with open(output_file, "w", encoding="utf-8") as f:
            yaml.dump(
                self._settings, f, default_flow_style=False, allow_unicode=True
            )

        logger.info(f"Settings saved to {output_file}")

    except Exception as e:
        logger.error(f"Failed to save settings: {e}")
        raise

def get_all(self) -> Dict[str, Any]:
    """
    Get all settings.

    Returns
    -------
    Dict[str, Any]
        Complete settings dictionary.
    """
    return self._settings.copy()

def register_singleton(self, name: str, instance: Any) -> None:
    """
    Register a singleton instance.

    Parameters
    ----------
    name : str
        Dependency name
    instance : Any
        Instance to register
    """
    self._singletons[name] = instance

    logger.debug(
        f"Registered singleton: {name}", extra={"type": type(instance).__name__}
    )

def register_factory(self, name: str, factory: Callable[[], Any]) -> None:
    """
    Register a factory function.

    Factory is called each time dependency is resolved.

    Parameters
    ----------
    name : str
        Dependency name
    factory : Callable[[], Any]
        Factory function that creates instances
    """
    self._factories[name] = factory

    logger.debug(f"Registered factory: {name}")

def register_type(self, name: str, cls: Type) -> None:
    """
    Register a type for lazy instantiation.

    Type is instantiated (with no-arg constructor) when first resolved.

    Parameters
    ----------
    name : str
        Dependency name
    cls : Type
        Class to instantiate
    """
    self._types[name] = cls

    logger.debug(f"Registered type: {name}", extra={"class": cls.__name__})

def resolve(self, name: str) -> Any:
    """
    Resolve dependency by name.

    Resolution order: singleton, factory, type.

    Parameters
    ----------
    name : str
        Dependency name

    Returns
    -------
    Any
        Resolved dependency instance

    Raises
    ------
    ValueError
        If dependency not found
    """
    # Try singleton first
    if name in self._singletons:
        return self._singletons[name]

    # Try factory
    if name in self._factories:
        instance = self._factories[name]()
        logger.debug(f"Created instance from factory: {name}")
        return instance

    # Try type (lazy singleton)
    if name in self._types:
        cls = self._types[name]
        instance = cls()
        # Cache as singleton
        self._singletons[name] = instance
        logger.debug(
            f"Created instance from type: {name}", extra={"class": cls.__name__}
        )
        return instance

    # Not found
    available = self.get_registered_names()
    raise ValueError(f"Dependency not found: '{name}'. " f"Available: {available}")

def is_registered(self, name: str) -> bool:
    """
    Check if dependency is registered.

    Parameters
    ----------
    name : str
        Dependency name.

    Returns
    -------
    bool
        True if registered.
    """
    return (
        name in self._singletons or name in self._factories or name in self._types
    )

def get_registered_names(self) -> list[str]:
    """
    Get list of registered dependency names.

    Returns
    -------
    list[str]
        List of dependency names.
    """
    return list(
        set(self._singletons.keys())
        | set(self._factories.keys())
        | set(self._types.keys())
    )

def clear(self) -> None:
    """Clear all registrations."""
    count = len(self.get_registered_names())

    self._singletons.clear()
    self._factories.clear()
    self._types.clear()

    logger.info(f"Cleared DIContainer: {count} registrations removed")

def unregister(self, name: str) -> bool:
    """
    Unregister a dependency.

    Parameters
    ----------
    name : str
        Dependency name.

    Returns
    -------
    bool
        True if unregistered, False if not found.
    """
    removed = False

    if name in self._singletons:
        del self._singletons[name]
        removed = True

    if name in self._factories:
        del self._factories[name]
        removed = True

    if name in self._types:
        del self._types[name]
        removed = True

    if removed:
        logger.debug(f"Unregistered dependency: {name}")

    return removed

def get_analysis(self, analysis_id: str) -> Optional[Dict[str, Any]]:
    """
    Get analysis configuration by ID.

    Parameters
    ----------
    analysis_id : str
        Analysis identifier (e.g., 'UC1_1')

    Returns
    -------
    Optional[Dict[str, Any]]
        Analysis configuration or None if not found
    """
    analysis = self._analyses.get(analysis_id)

    if analysis is None:
        logger.warning(f"Analysis not found: {analysis_id}")

    return analysis

def get_all_analyses(self) -> Dict[str, Dict[str, Any]]:
    """
    Get all registered analyses.

    Returns
    -------
    Dict[str, Dict[str, Any]]
        Dictionary mapping analysis IDs to configurations.
    """
    return self._analyses.copy()

def get_analyses_by_use_case(self, use_case: str) -> List[Dict[str, Any]]:
    """
    Get all analyses for a specific Use Case.

    Parameters
    ----------
    use_case : str
        Use Case identifier (e.g., 'UC1')

    Returns
    -------
    List[Dict[str, Any]]
        List of analysis configurations
    """
    return [
        analysis
        for analysis_id, analysis in self._analyses.items()
        if analysis_id.startswith(use_case)
    ]

def get_analysis_ids(self) -> List[str]:
    """
    Get list of all analysis IDs.

    Returns
    -------
    List[str]
        List of analysis identifiers.
    """
    return list(self._analyses.keys())

def get_use_cases(self) -> List[str]:
    """
    Get list of unique Use Cases.

    Returns
    -------
    List[str]
        List of Use Case identifiers
    """
    use_cases = set()

    for analysis_id in self._analyses.keys():
        # Extract UC prefix (e.g., 'UC1' from 'UC1_1')
        if "_" in analysis_id:
            uc = analysis_id.split("_")[0]
            use_cases.add(uc)

    return sorted(list(use_cases))

def analysis_exists(self, analysis_id: str) -> bool:
    """
    Check if analysis exists.

    Parameters
    ----------
    analysis_id : str
        Analysis identifier.

    Returns
    -------
    bool
        True if analysis is registered.
    """
    return analysis_id in self._analyses

def get_analysis_plot_type(self, analysis_id: str) -> Optional[str]:
    """
    Get plot type for analysis.

    Parameters
    ----------
    analysis_id : str
        Analysis identifier

    Returns
    -------
    Optional[str]
        Plot type (e.g., 'heatmap', 'bar_chart') or None
    """
    analysis = self.get_analysis(analysis_id)

    if analysis is None:
        return None

    return analysis.get("plot_type")

def reload(self) -> None:
    """Reload all analysis configurations from files."""
    logger.info("Reloading analysis configurations")
    self._analyses.clear()
    self._load_analyses()

def get_stats(self) -> Dict[str, Any]:
    """
    Get registry statistics.

    Returns
    -------
    Dict[str, Any]
        Statistics including total analyses, use cases, etc.
    """
    use_cases = self.get_use_cases()
    use_case_counts = {
        uc: len(self.get_analyses_by_use_case(uc)) for uc in use_cases
    }

    return {
        "total_analyses": len(self._analyses),
        "total_use_cases": len(use_cases),
        "use_cases": use_cases,
        "analyses_per_use_case": use_case_counts,
    }

def get_database_path(self, database_name: str) -> Path:
    """
    Get database file path.

    Parameters
    ----------
    database_name : str
        Database name ('biorempp', 'kegg', 'hadeg', 'toxcsm')

    Returns
    -------
    Path
        Path to database file

    Raises
    ------
    ValueError
        If database name is unknown
    """
    if database_name not in self._config:
        available = list(self._config.keys())
        raise ValueError(
            f"Unknown database: '{database_name}'. " f"Available: {available}"
        )

    filepath = self._config[database_name]["filepath"]
    return Path(filepath)

def get_database_encoding(self, database_name: str, default: str = "utf-8") -> str:
    """
    Get database file encoding.

    Parameters
    ----------
    database_name : str
        Database name.
    default : str, default='utf-8'
        Default encoding if not specified.

    Returns
    -------
    str
        File encoding.
    """
    if database_name not in self._config:
        return default

    return self._config[database_name].get("encoding", default)

def get_database_separator(self, database_name: str, default: str = ";") -> str:
    """
    Get database CSV separator.

    Parameters
    ----------
    database_name : str
        Database name.
    default : str, default=';'
        Default separator if not specified.

    Returns
    -------
    str
        CSV separator.
    """
    if database_name not in self._config:
        return default

    return self._config[database_name].get("separator", default)

def get_all_database_paths(self) -> Dict[str, Path]:
    """
    Get all database paths.

    Returns
    -------
    Dict[str, Path]
        Dictionary mapping database names to paths
    """
    return {name: Path(cfg["filepath"]) for name, cfg in self._config.items()}

def validate_paths(self) -> Dict[str, bool]:
    """
    Validate that all database files exist.

    Returns
    -------
    Dict[str, bool]
        Dictionary mapping database names to existence status
    """
    status = {}

    for name, path in self.get_all_database_paths().items():
        exists = path.exists()
        status[name] = exists

        if not exists:
            logger.warning(f"Database file not found: {name} ({path})")

    return status

def get_database_info(self, database_name: str) -> Dict[str, str]:
    """
    Get complete database configuration.

    Parameters
    ----------
    database_name : str
        Database name.

    Returns
    -------
    Dict[str, str]
        Database configuration dictionary.

    Raises
    ------
    ValueError
        If database name is unknown.
    """
    if database_name not in self._config:
        available = list(self._config.keys())
        raise ValueError(
            f"Unknown database: '{database_name}'. " f"Available: {available}"
        )

    return self._config[database_name].copy()

def get_available_databases(self) -> list[str]:
    """
    Get list of available database names.

    Returns
    -------
    list[str]
        List of database names.
    """
    return list(self._config.keys())