Re add handle deprectaed kwarg method

Author: FBumann

flixopt/config.py

@@ -29,6 +29,9 @@
 SUCCESS_LEVEL = 25
 logging.addLevelName(SUCCESS_LEVEL, 'SUCCESS')
 
+# Deprecation removal version - update this when planning the next major version
+DEPRECATION_REMOVAL_VERSION = '6.0.0'
+
 
 class MultilineFormatter(logging.Formatter):
     """Custom formatter that handles multi-line messages with box-style borders.

flixopt/structure.py

@@ -24,6 +24,7 @@
 import xarray as xr
 
 from . import io as fx_io
+from .config import DEPRECATION_REMOVAL_VERSION
 from .core import FlowSystemDimensions, TimeSeriesData, get_dataarray_stats
 
 if TYPE_CHECKING:  # for type checking and preventing circular imports
@@ -513,6 +514,79 @@ def _extract_dataarrays_recursive(self, obj, context_name: str = '') -> tuple[An
         else:
             return self._serialize_to_basic_types(obj), extracted_arrays
 
+    def _handle_deprecated_kwarg(
+        self,
+        kwargs: dict,
+        old_name: str,
+        new_name: str,
+        current_value: Any = None,
+        transform: callable = None,
+        check_conflict: bool = True,
+        additional_warning_message: str = '',
+    ) -> Any:
+        """
+        Handle a deprecated keyword argument by issuing a warning and returning the appropriate value.
+
+        This centralizes the deprecation pattern used across multiple classes (Source, Sink, InvestParameters, etc.).
+
+        Args:
+            kwargs: Dictionary of keyword arguments to check and modify
+            old_name: Name of the deprecated parameter
+            new_name: Name of the replacement parameter
+            current_value: Current value of the new parameter (if already set)
+            transform: Optional callable to transform the old value before returning (e.g., lambda x: [x] to wrap in list)
+            check_conflict: Whether to check if both old and new parameters are specified (default: True).
+                Note: For parameters with non-None default values (e.g., bool parameters with default=False),
+                set check_conflict=False since we cannot distinguish between an explicit value and the default.
+            additional_warning_message: Add a custom message which gets appended with a line break to the default warning.
+
+        Returns:
+            The value to use (either from old parameter or current_value)
+
+        Raises:
+            ValueError: If both old and new parameters are specified and check_conflict is True
+
+        Example:
+            # For parameters where None is the default (conflict checking works):
+            value = self._handle_deprecated_kwarg(kwargs, 'old_param', 'new_param', current_value)
+
+            # For parameters with non-None defaults (disable conflict checking):
+            mandatory = self._handle_deprecated_kwarg(
+                kwargs, 'optional', 'mandatory', mandatory,
+                transform=lambda x: not x,
+                check_conflict=False  # Cannot detect if mandatory was explicitly passed
+            )
+        """
+        import warnings
+
+        old_value = kwargs.pop(old_name, None)
+        if old_value is not None:
+            # Build base warning message
+            base_warning = f'The use of the "{old_name}" argument is deprecated. Use the "{new_name}" argument instead. Will be removed in v{DEPRECATION_REMOVAL_VERSION}.'
+
+            # Append additional message on a new line if provided
+            if additional_warning_message:
+                # Normalize whitespace: strip leading/trailing whitespace
+                extra_msg = additional_warning_message.strip()
+                if extra_msg:
+                    base_warning += '\n' + extra_msg
+
+            warnings.warn(
+                base_warning,
+                DeprecationWarning,
+                stacklevel=3,  # Stack: this method -> __init__ -> caller
+            )
+            # Check for conflicts: only raise error if both were explicitly provided
+            if check_conflict and current_value is not None:
+                raise ValueError(f'Either {old_name} or {new_name} can be specified, but not both.')
+
+            # Apply transformation if provided
+            if transform is not None:
+                return transform(old_value)
+            return old_value
+
+        return current_value
+
     def _validate_kwargs(self, kwargs: dict, class_name: str = None) -> None:
         """
         Validate that no unexpected keyword arguments are present in kwargs.