flixopt 2.2.0b0__py3-none-any.whl → 3.0.0__py3-none-any.whl

flixopt/config.py

@@ -1,259 +1,621 @@
+from __future__ import annotations
+
 import logging
-import os
-import types
-from dataclasses import dataclass, fields, is_dataclass
-from typing import Annotated, Literal, Optional
+import sys
+import warnings
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from types import MappingProxyType
+from typing import Literal
 
 import yaml
 from rich.console import Console
 from rich.logging import RichHandler
+from rich.style import Style
+from rich.theme import Theme
+
+__all__ = ['CONFIG', 'change_logging_level']
 
 logger = logging.getLogger('flixopt')
 
 
-def merge_configs(defaults: dict, overrides: dict) -> dict:
-    """
-    Merge the default configuration with user-provided overrides.
-    Args:
-        defaults: Default configuration dictionary.
-        overrides: User configuration dictionary.
-    Returns:
-        Merged configuration dictionary.
-    """
-    for key, value in overrides.items():
-        if isinstance(value, dict) and key in defaults and isinstance(defaults[key], dict):
-            # Recursively merge nested dictionaries
-            defaults[key] = merge_configs(defaults[key], value)
-        else:
-            # Override the default value
-            defaults[key] = value
-    return defaults
+# SINGLE SOURCE OF TRUTH - immutable to prevent accidental modification
+_DEFAULTS = MappingProxyType(
+    {
+        'config_name': 'flixopt',
+        'logging': MappingProxyType(
+            {
+                'level': 'INFO',
+                'file': None,
+                'rich': False,
+                'console': False,
+                'max_file_size': 10_485_760,  # 10MB
+                'backup_count': 5,
+                'date_format': '%Y-%m-%d %H:%M:%S',
+                'format': '%(message)s',
+                'console_width': 120,
+                'show_path': False,
+                'show_logger_name': False,
+                'colors': MappingProxyType(
+                    {
+                        'DEBUG': '\033[90m',  # Bright Black/Gray
+                        'INFO': '\033[0m',  # Default/White
+                        'WARNING': '\033[33m',  # Yellow
+                        'ERROR': '\033[31m',  # Red
+                        'CRITICAL': '\033[1m\033[31m',  # Bold Red
+                    }
+                ),
+            }
+        ),
+        'modeling': MappingProxyType(
+            {
+                'big': 10_000_000,
+                'epsilon': 1e-5,
+                'big_binary_bound': 100_000,
+            }
+        ),
+    }
+)
 
 
-def dataclass_from_dict_with_validation(cls, data: dict):
-    """
-    Recursively initialize a dataclass from a dictionary.
+class CONFIG:
+    """Configuration for flixopt library.
+
+    Always call ``CONFIG.apply()`` after changes.
+
+    Attributes:
+        Logging: Logging configuration.
+        Modeling: Optimization modeling parameters.
+        config_name: Configuration name.
+
+    Examples:
+        ```python
+        CONFIG.Logging.console = True
+        CONFIG.Logging.level = 'DEBUG'
+        CONFIG.apply()
+        ```
+
+        Load from YAML file:
+
+        ```yaml
+        logging:
+          level: DEBUG
+          console: true
+          file: app.log
+        ```
     """
-    if not is_dataclass(cls):
-        raise TypeError(f'{cls} must be a dataclass')
-
-    # Build kwargs for the dataclass constructor
-    kwargs = {}
-    for field in fields(cls):
-        field_name = field.name
-        field_type = field.type
-        field_value = data.get(field_name)
-
-        # If the field type is a dataclass and the value is a dict, recursively initialize
-        if is_dataclass(field_type) and isinstance(field_value, dict):
-            kwargs[field_name] = dataclass_from_dict_with_validation(field_type, field_value)
-        else:
-            kwargs[field_name] = field_value  # Pass as-is if no special handling is needed
 
-    return cls(**kwargs)
+    class Logging:
+        """Logging configuration.
+
+        Silent by default. Enable via ``console=True`` or ``file='path'``.
+
+        Attributes:
+            level: Logging level.
+            file: Log file path for file logging.
+            console: Enable console output.
+            rich: Use Rich library for enhanced output.
+            max_file_size: Max file size before rotation.
+            backup_count: Number of backup files to keep.
+            date_format: Date/time format string.
+            format: Log message format string.
+            console_width: Console width for Rich handler.
+            show_path: Show file paths in messages.
+            show_logger_name: Show logger name in messages.
+            Colors: ANSI color codes for log levels.
+
+        Examples:
+            ```python
+            # File logging with rotation
+            CONFIG.Logging.file = 'app.log'
+            CONFIG.Logging.max_file_size = 5_242_880  # 5MB
+            CONFIG.apply()
+
+            # Rich handler with stdout
+            CONFIG.Logging.console = True  # or 'stdout'
+            CONFIG.Logging.rich = True
+            CONFIG.apply()
+
+            # Console output to stderr
+            CONFIG.Logging.console = 'stderr'
+            CONFIG.apply()
+            ```
+        """
 
+        level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = _DEFAULTS['logging']['level']
+        file: str | None = _DEFAULTS['logging']['file']
+        rich: bool = _DEFAULTS['logging']['rich']
+        console: bool | Literal['stdout', 'stderr'] = _DEFAULTS['logging']['console']
+        max_file_size: int = _DEFAULTS['logging']['max_file_size']
+        backup_count: int = _DEFAULTS['logging']['backup_count']
+        date_format: str = _DEFAULTS['logging']['date_format']
+        format: str = _DEFAULTS['logging']['format']
+        console_width: int = _DEFAULTS['logging']['console_width']
+        show_path: bool = _DEFAULTS['logging']['show_path']
+        show_logger_name: bool = _DEFAULTS['logging']['show_logger_name']
+
+        class Colors:
+            """ANSI color codes for log levels.
+
+            Attributes:
+                DEBUG: ANSI color for DEBUG level.
+                INFO: ANSI color for INFO level.
+                WARNING: ANSI color for WARNING level.
+                ERROR: ANSI color for ERROR level.
+                CRITICAL: ANSI color for CRITICAL level.
+
+            Examples:
+                ```python
+                CONFIG.Logging.Colors.INFO = '\\033[32m'  # Green
+                CONFIG.Logging.Colors.ERROR = '\\033[1m\\033[31m'  # Bold red
+                CONFIG.apply()
+                ```
+
+            Common ANSI codes:
+                - '\\033[30m' - Black
+                - '\\033[31m' - Red
+                - '\\033[32m' - Green
+                - '\\033[33m' - Yellow
+                - '\\033[34m' - Blue
+                - '\\033[35m' - Magenta
+                - '\\033[36m' - Cyan
+                - '\\033[37m' - White
+                - '\\033[90m' - Bright Black/Gray
+                - '\\033[0m' - Reset to default
+                - '\\033[1m\\033[3Xm' - Bold (replace X with color code 0-7)
+                - '\\033[2m\\033[3Xm' - Dim (replace X with color code 0-7)
+            """
+
+            DEBUG: str = _DEFAULTS['logging']['colors']['DEBUG']
+            INFO: str = _DEFAULTS['logging']['colors']['INFO']
+            WARNING: str = _DEFAULTS['logging']['colors']['WARNING']
+            ERROR: str = _DEFAULTS['logging']['colors']['ERROR']
+            CRITICAL: str = _DEFAULTS['logging']['colors']['CRITICAL']
+
+    class Modeling:
+        """Optimization modeling parameters.
+
+        Attributes:
+            big: Large number for big-M constraints.
+            epsilon: Tolerance for numerical comparisons.
+            big_binary_bound: Upper bound for binary constraints.
+        """
 
-@dataclass()
-class ValidatedConfig:
-    def __setattr__(self, name, value):
-        if field := self.__dataclass_fields__.get(name):
-            if metadata := getattr(field.type, '__metadata__', None):
-                assert metadata[0](value), f'Invalid value passed to {name!r}: {value=}'
-        super().__setattr__(name, value)
+        big: int = _DEFAULTS['modeling']['big']
+        epsilon: float = _DEFAULTS['modeling']['epsilon']
+        big_binary_bound: int = _DEFAULTS['modeling']['big_binary_bound']
 
+    config_name: str = _DEFAULTS['config_name']
 
-@dataclass
-class LoggingConfig(ValidatedConfig):
-    level: Annotated[
-        Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
-        lambda level: level in ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
-    ]
-    file: Annotated[str, lambda file: isinstance(file, str)]
-    rich: Annotated[bool, lambda rich: isinstance(rich, bool)]
+    @classmethod
+    def reset(cls):
+        """Reset all configuration values to defaults."""
+        for key, value in _DEFAULTS['logging'].items():
+            if key == 'colors':
+                # Reset nested Colors class
+                for color_key, color_value in value.items():
+                    setattr(cls.Logging.Colors, color_key, color_value)
+            else:
+                setattr(cls.Logging, key, value)
+
+        for key, value in _DEFAULTS['modeling'].items():
+            setattr(cls.Modeling, key, value)
+
+        cls.config_name = _DEFAULTS['config_name']
+        cls.apply()
 
+    @classmethod
+    def apply(cls):
+        """Apply current configuration to logging system."""
+        # Convert Colors class attributes to dict
+        colors_dict = {
+            'DEBUG': cls.Logging.Colors.DEBUG,
+            'INFO': cls.Logging.Colors.INFO,
+            'WARNING': cls.Logging.Colors.WARNING,
+            'ERROR': cls.Logging.Colors.ERROR,
+            'CRITICAL': cls.Logging.Colors.CRITICAL,
+        }
+        valid_levels = list(colors_dict)
+        if cls.Logging.level.upper() not in valid_levels:
+            raise ValueError(f"Invalid log level '{cls.Logging.level}'. Must be one of: {', '.join(valid_levels)}")
+
+        if cls.Logging.max_file_size <= 0:
+            raise ValueError('max_file_size must be positive')
+
+        if cls.Logging.backup_count < 0:
+            raise ValueError('backup_count must be non-negative')
+
+        if cls.Logging.console not in (False, True, 'stdout', 'stderr'):
+            raise ValueError(f"console must be False, True, 'stdout', or 'stderr', got {cls.Logging.console}")
+
+        _setup_logging(
+            default_level=cls.Logging.level,
+            log_file=cls.Logging.file,
+            use_rich_handler=cls.Logging.rich,
+            console=cls.Logging.console,
+            max_file_size=cls.Logging.max_file_size,
+            backup_count=cls.Logging.backup_count,
+            date_format=cls.Logging.date_format,
+            format=cls.Logging.format,
+            console_width=cls.Logging.console_width,
+            show_path=cls.Logging.show_path,
+            show_logger_name=cls.Logging.show_logger_name,
+            colors=colors_dict,
+        )
 
-@dataclass
-class ModelingConfig(ValidatedConfig):
-    BIG: Annotated[int, lambda x: isinstance(x, int)]
-    EPSILON: Annotated[float, lambda x: isinstance(x, float)]
-    BIG_BINARY_BOUND: Annotated[int, lambda x: isinstance(x, int)]
+    @classmethod
+    def load_from_file(cls, config_file: str | Path):
+        """Load configuration from YAML file and apply it.
 
+        Args:
+            config_file: Path to the YAML configuration file.
 
-@dataclass
-class ConfigSchema(ValidatedConfig):
-    config_name: Annotated[str, lambda x: isinstance(x, str)]
-    logging: LoggingConfig
-    modeling: ModelingConfig
+        Raises:
+            FileNotFoundError: If the config file does not exist.
+        """
+        config_path = Path(config_file)
+        if not config_path.exists():
+            raise FileNotFoundError(f'Config file not found: {config_file}')
 
+        with config_path.open() as file:
+            config_dict = yaml.safe_load(file) or {}
+            cls._apply_config_dict(config_dict)
 
-class CONFIG:
-    """
-    A configuration class that stores global configuration values as class attributes.
-    """
-
-    config_name: str = None
-    modeling: ModelingConfig = None
-    logging: LoggingConfig = None
+        cls.apply()
 
     @classmethod
-    def load_config(cls, user_config_file: Optional[str] = None):
-        """
-        Initialize configuration using defaults or user-specified file.
-        """
-        # Default config file
-        default_config_path = os.path.join(os.path.dirname(__file__), 'config.yaml')
-
-        if user_config_file is None:
-            with open(default_config_path, 'r') as file:
-                new_config = yaml.safe_load(file)
-        elif not os.path.exists(user_config_file):
-            raise FileNotFoundError(f'Config file not found: {user_config_file}')
-        else:
-            with open(user_config_file, 'r') as user_file:
-                new_config = yaml.safe_load(user_file)
-
-        # Convert the merged config to ConfigSchema
-        config_data = dataclass_from_dict_with_validation(ConfigSchema, new_config)
+    def _apply_config_dict(cls, config_dict: dict):
+        """Apply configuration dictionary to class attributes.
 
-        # Store the configuration in the class as class attributes
-        cls.logging = config_data.logging
-        cls.modeling = config_data.modeling
-        cls.config_name = config_data.config_name
-
-        setup_logging(default_level=cls.logging.level, log_file=cls.logging.file, use_rich_handler=cls.logging.rich)
+        Args:
+            config_dict: Dictionary containing configuration values.
+        """
+        for key, value in config_dict.items():
+            if key == 'logging' and isinstance(value, dict):
+                for nested_key, nested_value in value.items():
+                    if nested_key == 'colors' and isinstance(nested_value, dict):
+                        # Handle nested colors under logging
+                        for color_key, color_value in nested_value.items():
+                            setattr(cls.Logging.Colors, color_key, color_value)
+                    else:
+                        setattr(cls.Logging, nested_key, nested_value)
+            elif key == 'modeling' and isinstance(value, dict):
+                for nested_key, nested_value in value.items():
+                    setattr(cls.Modeling, nested_key, nested_value)
+            elif hasattr(cls, key):
+                setattr(cls, key, value)
 
     @classmethod
     def to_dict(cls):
+        """Convert the configuration class into a dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation of the current configuration.
         """
-        Convert the configuration class into a dictionary for JSON serialization.
-        Handles dataclasses and simple types like str, int, etc.
-        """
-        config_dict = {}
-        for attribute, value in cls.__dict__.items():
-            # Only consider attributes (not methods, etc.)
-            if (
-                not attribute.startswith('_')
-                and not isinstance(value, (types.FunctionType, types.MethodType))
-                and not isinstance(value, classmethod)
-            ):
-                if is_dataclass(value):
-                    config_dict[attribute] = value.__dict__
-                else:  # Assuming only basic types here!
-                    config_dict[attribute] = value
-
-        return config_dict
-
-
-class MultilineFormater(logging.Formatter):
-    def format(self, record):
-        message_lines = record.getMessage().split('\n')
+        return {
+            'config_name': cls.config_name,
+            'logging': {
+                'level': cls.Logging.level,
+                'file': cls.Logging.file,
+                'rich': cls.Logging.rich,
+                'console': cls.Logging.console,
+                'max_file_size': cls.Logging.max_file_size,
+                'backup_count': cls.Logging.backup_count,
+                'date_format': cls.Logging.date_format,
+                'format': cls.Logging.format,
+                'console_width': cls.Logging.console_width,
+                'show_path': cls.Logging.show_path,
+                'show_logger_name': cls.Logging.show_logger_name,
+                'colors': {
+                    'DEBUG': cls.Logging.Colors.DEBUG,
+                    'INFO': cls.Logging.Colors.INFO,
+                    'WARNING': cls.Logging.Colors.WARNING,
+                    'ERROR': cls.Logging.Colors.ERROR,
+                    'CRITICAL': cls.Logging.Colors.CRITICAL,
+                },
+            },
+            'modeling': {
+                'big': cls.Modeling.big,
+                'epsilon': cls.Modeling.epsilon,
+                'big_binary_bound': cls.Modeling.big_binary_bound,
+            },
+        }
+
+
+class MultilineFormatter(logging.Formatter):
+    """Formatter that handles multi-line messages with consistent prefixes.
 
-        # Prepare the log prefix (timestamp + log level)
+    Args:
+        fmt: Log message format string.
+        datefmt: Date/time format string.
+        show_logger_name: Show logger name in log messages.
+    """
+
+    def __init__(self, fmt: str = '%(message)s', datefmt: str | None = None, show_logger_name: bool = False):
+        super().__init__(fmt=fmt, datefmt=datefmt)
+        self.show_logger_name = show_logger_name
+
+    def format(self, record) -> str:
+        record.message = record.getMessage()
+        message_lines = self._style.format(record).split('\n')
         timestamp = self.formatTime(record, self.datefmt)
-        log_level = record.levelname.ljust(8)  # Align log levels for consistency
-        log_prefix = f'{timestamp} | {log_level} |'
+        log_level = record.levelname.ljust(8)
 
-        # Format all lines
-        first_line = [f'{log_prefix} {message_lines[0]}']
-        if len(message_lines) > 1:
-            lines = first_line + [f'{log_prefix} {line}' for line in message_lines[1:]]
+        if self.show_logger_name:
+            # Truncate long logger names for readability
+            logger_name = record.name if len(record.name) <= 20 else f'...{record.name[-17:]}'
+            log_prefix = f'{timestamp} | {log_level} | {logger_name.ljust(20)} |'
         else:
-            lines = first_line
+            log_prefix = f'{timestamp} | {log_level} |'
+
+        indent = ' ' * (len(log_prefix) + 1)  # +1 for the space after prefix
+
+        lines = [f'{log_prefix} {message_lines[0]}']
+        if len(message_lines) > 1:
+            lines.extend([f'{indent}{line}' for line in message_lines[1:]])
 
         return '\n'.join(lines)
 
 
-class ColoredMultilineFormater(MultilineFormater):
-    # ANSI escape codes for colors
-    COLORS = {
-        'DEBUG': '\033[32m',  # Green
-        'INFO': '\033[34m',  # Blue
-        'WARNING': '\033[33m',  # Yellow
-        'ERROR': '\033[31m',  # Red
-        'CRITICAL': '\033[1m\033[31m',  # Bold Red
-    }
+class ColoredMultilineFormatter(MultilineFormatter):
+    """Formatter that adds ANSI colors to multi-line log messages.
+
+    Args:
+        fmt: Log message format string.
+        datefmt: Date/time format string.
+        colors: Dictionary of ANSI color codes for each log level.
+        show_logger_name: Show logger name in log messages.
+    """
+
     RESET = '\033[0m'
 
+    def __init__(
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        colors: dict[str, str] | None = None,
+        show_logger_name: bool = False,
+    ):
+        super().__init__(fmt=fmt, datefmt=datefmt, show_logger_name=show_logger_name)
+        self.COLORS = (
+            colors
+            if colors is not None
+            else {
+                'DEBUG': '\033[90m',
+                'INFO': '\033[0m',
+                'WARNING': '\033[33m',
+                'ERROR': '\033[31m',
+                'CRITICAL': '\033[1m\033[31m',
+            }
+        )
+
     def format(self, record):
         lines = super().format(record).splitlines()
         log_color = self.COLORS.get(record.levelname, self.RESET)
+        formatted_lines = [f'{log_color}{line}{self.RESET}' for line in lines]
+        return '\n'.join(formatted_lines)
 
-        # Create a formatted message for each line separately
-        formatted_lines = []
-        for line in lines:
-            formatted_lines.append(f'{log_color}{line}{self.RESET}')
 
-        return '\n'.join(formatted_lines)
+def _create_console_handler(
+    use_rich: bool = False,
+    stream: Literal['stdout', 'stderr'] = 'stdout',
+    console_width: int = 120,
+    show_path: bool = False,
+    show_logger_name: bool = False,
+    date_format: str = '%Y-%m-%d %H:%M:%S',
+    format: str = '%(message)s',
+    colors: dict[str, str] | None = None,
+) -> logging.Handler:
+    """Create a console logging handler.
 
+    Args:
+        use_rich: If True, use RichHandler with color support.
+        stream: Output stream
+        console_width: Width of the console for Rich handler.
+        show_path: Show file paths in log messages (Rich only).
+        show_logger_name: Show logger name in log messages.
+        date_format: Date/time format string.
+        format: Log message format string.
+        colors: Dictionary of ANSI color codes for each log level.
 
-def _get_logging_handler(log_file: Optional[str] = None, use_rich_handler: bool = False) -> logging.Handler:
-    """Returns a logging handler for the given log file."""
-    if use_rich_handler and log_file is None:
-        # RichHandler for console output
-        console = Console(width=120)
-        rich_handler = RichHandler(
+    Returns:
+        Configured logging handler (RichHandler or StreamHandler).
+    """
+    # Determine the stream object
+    stream_obj = sys.stdout if stream == 'stdout' else sys.stderr
+
+    if use_rich:
+        # Convert ANSI codes to Rich theme
+        if colors:
+            theme_dict = {}
+            for level, ansi_code in colors.items():
+                # Rich can parse ANSI codes directly!
+                try:
+                    style = Style.from_ansi(ansi_code)
+                    theme_dict[f'logging.level.{level.lower()}'] = style
+                except Exception:
+                    # Fallback to default if parsing fails
+                    pass
+
+            theme = Theme(theme_dict) if theme_dict else None
+        else:
+            theme = None
+
+        console = Console(width=console_width, theme=theme, file=stream_obj)
+        handler = RichHandler(
             console=console,
             rich_tracebacks=True,
             omit_repeated_times=True,
-            show_path=False,
-            log_time_format='%Y-%m-%d %H:%M:%S',
-        )
-        rich_handler.setFormatter(logging.Formatter('%(message)s'))  # Simplified formatting
-
-        return rich_handler
-    elif log_file is None:
-        # Regular Logger with custom formating enabled
-        file_handler = logging.StreamHandler()
-        file_handler.setFormatter(
-            ColoredMultilineFormater(
-                fmt='%(message)s',
-                datefmt='%Y-%m-%d %H:%M:%S',
-            )
+            show_path=show_path,
+            log_time_format=date_format,
         )
-        return file_handler
+        handler.setFormatter(logging.Formatter(format))
     else:
-        # FileHandler for file output
-        file_handler = logging.FileHandler(log_file)
-        file_handler.setFormatter(
-            MultilineFormater(
-                fmt='%(message)s',
-                datefmt='%Y-%m-%d %H:%M:%S',
+        handler = logging.StreamHandler(stream=stream_obj)
+        handler.setFormatter(
+            ColoredMultilineFormatter(
+                fmt=format,
+                datefmt=date_format,
+                colors=colors,
+                show_logger_name=show_logger_name,
             )
         )
-        return file_handler
 
+    return handler
+
+
+def _create_file_handler(
+    log_file: str,
+    max_file_size: int = 10_485_760,
+    backup_count: int = 5,
+    show_logger_name: bool = False,
+    date_format: str = '%Y-%m-%d %H:%M:%S',
+    format: str = '%(message)s',
+) -> RotatingFileHandler:
+    """Create a rotating file handler to prevent huge log files.
+
+    Args:
+        log_file: Path to the log file.
+        max_file_size: Maximum size in bytes before rotation.
+        backup_count: Number of backup files to keep.
+        show_logger_name: Show logger name in log messages.
+        date_format: Date/time format string.
+        format: Log message format string.
+
+    Returns:
+        Configured RotatingFileHandler (without colors).
+    """
 
-def setup_logging(
+    # Ensure parent directory exists
+    log_path = Path(log_file)
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+    except PermissionError as e:
+        raise PermissionError(f"Cannot create log directory '{log_path.parent}': Permission denied") from e
+
+    try:
+        handler = RotatingFileHandler(
+            log_file,
+            maxBytes=max_file_size,
+            backupCount=backup_count,
+            encoding='utf-8',
+        )
+    except PermissionError as e:
+        raise PermissionError(
+            f"Cannot write to log file '{log_file}': Permission denied. "
+            f'Choose a different location or check file permissions.'
+        ) from e
+
+    handler.setFormatter(
+        MultilineFormatter(
+            fmt=format,
+            datefmt=date_format,
+            show_logger_name=show_logger_name,
+        )
+    )
+    return handler
+
+
+def _setup_logging(
     default_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO',
-    log_file: Optional[str] = 'flixopt.log',
+    log_file: str | None = None,
     use_rich_handler: bool = False,
-):
-    """Setup logging configuration"""
-    logger = logging.getLogger('flixopt')  # Use a specific logger name for your package
-    logger.setLevel(get_logging_level_by_name(default_level))
-    # Clear existing handlers
-    if logger.hasHandlers():
-        logger.handlers.clear()
-
-    logger.addHandler(_get_logging_handler(use_rich_handler=use_rich_handler))
-    if log_file is not None:
-        logger.addHandler(_get_logging_handler(log_file, use_rich_handler=False))
+    console: bool | Literal['stdout', 'stderr'] = False,
+    max_file_size: int = 10_485_760,
+    backup_count: int = 5,
+    date_format: str = '%Y-%m-%d %H:%M:%S',
+    format: str = '%(message)s',
+    console_width: int = 120,
+    show_path: bool = False,
+    show_logger_name: bool = False,
+    colors: dict[str, str] | None = None,
+) -> None:
+    """Internal function to setup logging - use CONFIG.apply() instead.
+
+    Configures the flixopt logger with console and/or file handlers.
+    If no handlers are configured, adds NullHandler (library best practice).
 
-    return logger
+    Args:
+        default_level: Logging level for the logger.
+        log_file: Path to log file (None to disable file logging).
+        use_rich_handler: Use Rich for enhanced console output.
+        console: Enable console logging.
+        max_file_size: Maximum log file size before rotation.
+        backup_count: Number of backup log files to keep.
+        date_format: Date/time format for log messages.
+        format: Log message format string.
+        console_width: Console width for Rich handler.
+        show_path: Show file paths in log messages (Rich only).
+        show_logger_name: Show logger name in log messages.
+        colors: ANSI color codes for each log level.
+    """
+    logger = logging.getLogger('flixopt')
+    logger.setLevel(getattr(logging, default_level.upper()))
+    logger.propagate = False  # Prevent duplicate logs
+    logger.handlers.clear()
+
+    # Handle console parameter: False = disabled, True = stdout, 'stdout' = stdout, 'stderr' = stderr
+    if console:
+        # Convert True to 'stdout', keep 'stdout'/'stderr' as-is
+        stream = 'stdout' if console is True else console
+        logger.addHandler(
+            _create_console_handler(
+                use_rich=use_rich_handler,
+                stream=stream,
+                console_width=console_width,
+                show_path=show_path,
+                show_logger_name=show_logger_name,
+                date_format=date_format,
+                format=format,
+                colors=colors,
+            )
+        )
 
+    if log_file:
+        logger.addHandler(
+            _create_file_handler(
+                log_file=log_file,
+                max_file_size=max_file_size,
+                backup_count=backup_count,
+                show_logger_name=show_logger_name,
+                date_format=date_format,
+                format=format,
+            )
+        )
 
-def get_logging_level_by_name(level_name: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']) -> int:
-    possible_logging_levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
-    if level_name.upper() not in possible_logging_levels:
-        raise ValueError(f'Invalid logging level {level_name}')
-    else:
-        logging_level = getattr(logging, level_name.upper(), logging.WARNING)
-        return logging_level
+    # Library best practice: NullHandler if no handlers configured
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
 
 
 def change_logging_level(level_name: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']):
+    """Change the logging level for the flixopt logger and all its handlers.
+
+    .. deprecated:: 2.1.11
+        Use ``CONFIG.Logging.level = level_name`` and ``CONFIG.apply()`` instead.
+        This function will be removed in version 3.0.0.
+
+    Args:
+        level_name: The logging level to set.
+
+    Examples:
+        >>> change_logging_level('DEBUG')  # deprecated
+        >>> # Use this instead:
+        >>> CONFIG.Logging.level = 'DEBUG'
+        >>> CONFIG.apply()
+    """
+    warnings.warn(
+        'change_logging_level is deprecated and will be removed in version 3.0.0. '
+        'Use CONFIG.Logging.level = level_name and CONFIG.apply() instead.',
+        DeprecationWarning,
+        stacklevel=2,
+    )
     logger = logging.getLogger('flixopt')
-    logging_level = get_logging_level_by_name(level_name)
+    logging_level = getattr(logging, level_name.upper())
     logger.setLevel(logging_level)
     for handler in logger.handlers:
         handler.setLevel(logging_level)
+
+
+# Initialize default config
+CONFIG.apply()