Introduce @deprecated decorators for functions and enforce warnings as errors in tests

pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
     "posthog",
     "pyyaml",
     "platformdirs",
+    "deprecation"
 ]
 
 [project.urls]
@@ -216,6 +217,8 @@ required_plugins = [
 addopts = [
     "-nauto",
     "-vra",
+    "-ra",
+    "--showlocals",
     "--strict-config",
     "--strict-markers",
 ]
@@ -229,7 +232,9 @@ filterwarnings = [
     # ignore internal nbmake warnings
     'ignore:unclosed \<socket.socket:ResourceWarning',
     'ignore:unclosed event loop \<:ResourceWarning',
-    # ignore warnings generated while running tests
+    # convert internal warnings as errors
+    "error::DeprecationWarning:pybamm.*",
+    # ignore external DeprecationWarning
     "ignore::DeprecationWarning",
     "ignore::UserWarning",
     "ignore::RuntimeWarning",

src/pybamm/expression_tree/symbol.py

@@ -15,6 +15,7 @@
 import pybamm
 from pybamm.util import import_optional_dependency
 from pybamm.expression_tree.printing.print_name import prettify_print_name
+from deprecation import deprecated
 
 if TYPE_CHECKING:  # pragma: no cover
     import casadi
@@ -356,6 +357,12 @@ def domain(self, domain):
         )
 
     @property
+    @deprecated(
+        deprecated_in="25.1.0",
+        removed_in="26.0.0",
+        current_version=pybamm.__version__,
+        details="Use `symbol.domains` instead.",
+    )
     def auxiliary_domains(self):
         """Returns auxiliary domains."""
         raise NotImplementedError(
@@ -994,6 +1001,12 @@ def create_copy(
         children = self._children_for_copying(new_children)
         return self.__class__(self.name, children, domains=self.domains)
 
+    @deprecated(
+        deprecated_in="25.1.0",
+        removed_in="26.0.0",
+        current_version=pybamm.__version__,
+        details="Use `create_copy` instead.",
+    )
     def new_copy(
         self,
         new_children: list[Symbol] | None = None,

src/pybamm/parameters/parameter_values.py

@@ -4,6 +4,7 @@
 from pprint import pformat
 from warnings import warn
 from collections import defaultdict
+from pybamm.util import deprecate_arguments
 
 
 class ParameterValues:
@@ -417,6 +418,16 @@ def set_initial_ocps(
         return parameter_values
 
     @staticmethod
+    @deprecate_arguments(
+        deprecated_args={
+            "electrode diffusivity": "Use 'particle diffusivity' instead.",
+            "1 + dlnf/dlnc": "Use 'Thermodynamic factor' instead.",
+        },
+        deprecated_in="24.1.0",
+        removed_in="25.3.0",
+        current_version="25.1.0",
+        msg="Update your parameter names to avoid future compatibility issues.",
+    )
     def check_parameter_values(values):
         for param in list(values.keys()):
             if "propotional term" in param:

src/pybamm/simulation.py

@@ -7,7 +7,7 @@
 from datetime import timedelta
 import pybamm.telemetry
 from pybamm.util import import_optional_dependency
-
+from deprecation import deprecated
 from pybamm.expression_tree.operations.serialise import Serialise
 
 
@@ -156,8 +156,6 @@ def __setstate__(self, state):
         self.get_esoh_solver = lru_cache()(self._get_esoh_solver)
 
     def set_up_and_parameterise_experiment(self, solve_kwargs=None):
-        msg = "pybamm.simulation.set_up_and_parameterise_experiment is deprecated and not meant to be accessed by users."
-        warnings.warn(msg, DeprecationWarning, stacklevel=2)
         self._set_up_and_parameterise_experiment(solve_kwargs=solve_kwargs)
 
     def _set_up_and_parameterise_experiment(self, solve_kwargs=None):
@@ -238,11 +236,13 @@ def _set_up_and_parameterise_experiment(self, solve_kwargs=None):
                 parameterised_model
             )
 
+    @deprecated(
+        deprecated_in="25.1.0",
+        removed_in="26.0.0",
+        current_version=pybamm.__version__,
+        details="pybamm.set_parameters is deprecated and not meant to be accessed by users.",
+    )
     def set_parameters(self):
-        msg = (
-            "pybamm.set_parameters is deprecated and not meant to be accessed by users."
-        )
-        warnings.warn(msg, DeprecationWarning, stacklevel=2)
         self._set_parameters()
 
     def _set_parameters(self):

src/pybamm/solvers/base_solver.py

@@ -13,6 +13,7 @@
 import pybamm
 from pybamm.expression_tree.binary_operators import _Heaviside
 from pybamm import ParameterValues
+from pybamm.util import deprecate_arguments
 
 
 class BaseSolver:
@@ -1162,6 +1163,13 @@ def process_t_interp(self, t_interp):
 
         return t_interp
 
+    @deprecate_arguments(
+        deprecated_args={"npts": "Use 't_eval' instead."},
+        deprecated_in="25.1.0",
+        removed_in="25.3.0",
+        current_version="25.1.0",
+        msg="Please refer to the updated documentation.",
+    )
     def step(
         self,
         old_solution,

src/pybamm/util.py

@@ -7,7 +7,9 @@
 import pickle
 import timeit
 import difflib
+import warnings
 from warnings import warn
+import functools
 
 import pybamm
 
@@ -408,3 +410,46 @@ def import_optional_dependency(module_name, attribute=None):
     except ModuleNotFoundError as error:
         # Raise an ModuleNotFoundError if the module or attribute is not available
         raise ModuleNotFoundError(err_msg) from error
+
+
+def deprecate_arguments(
+    deprecated_args: dict[str, str],
+    deprecated_in: str,
+    removed_in: str,
+    current_version: str,
+    msg: str = "",
+):
+    """
+    Custom decorator to deprecate specific function arguments with an optional custom message.
+
+    Args:
+        deprecated_args (dict): Dictionary of deprecated argument names with details.
+            Example: {"old_arg": "Use 'new_arg' instead."}
+        deprecated_in (str): Version when the argument was deprecated.
+        removed_in (str): Version when the argument will be removed.
+        current_version (str): Current version of the package/module.
+        msg (str, optional): Additional custom message for the warning. Defaults to "".
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            for arg, message in deprecated_args.items():
+                if arg in kwargs:
+                    warning_message = (
+                        f"Argument '{arg}' is deprecated since version {deprecated_in} "
+                        f"and will be removed in version {removed_in}. (Current version: {current_version}) "
+                        f"{message}"
+                    )
+                    if msg:
+                        warning_message += f" {msg}"
+                    warnings.warn(
+                        warning_message,
+                        category=DeprecationWarning,
+                        stacklevel=2,
+                    )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator