FEAT: args deprecation decorator (#6086)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>
Co-authored-by: Sébastien Morais <146729917+SMoraisAnsys@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

doc/changelog.d/6086.added.md

@@ -0,0 +1 @@
+args deprecation decorator

src/ansys/aedt/core/application/analysis.py

@@ -51,6 +51,7 @@
 from ansys.aedt.core.generic.constants import VIEW
 from ansys.aedt.core.generic.file_utils import generate_unique_name
 from ansys.aedt.core.generic.file_utils import open_file
+from ansys.aedt.core.generic.general_methods import deprecate_argument
 from ansys.aedt.core.generic.general_methods import filter_tuple
 from ansys.aedt.core.generic.general_methods import is_linux
 from ansys.aedt.core.generic.general_methods import is_windows
@@ -782,8 +783,13 @@ def list_of_variations(self, setup=None, sweep=None):
                 return [""]
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def export_results(
         self,
+        analyze=False,
         export_folder=None,
         matrix_name="Original",
         matrix_type="S",
@@ -794,12 +800,13 @@ def export_results(
         include_gamma_comment=True,
         support_non_standard_touchstone_extension=False,
         variations=None,
-        **kwargs,
     ):
         """Export all available reports to a file, including profile, and convergence and sNp when applicable.
 
         Parameters
         ----------
+        analyze : bool
+            Whether to analyze before export. Solutions must be present for the design.
         export_folder : str, optional
             Full path to the project folder. The default is ``None``, in which case the
             working directory is used.
@@ -848,14 +855,6 @@ def export_results(
         >>> aedtapp.analyze()
         >>> exported_files = aedtapp.export_results()
         """
-        analyze = False
-        if "analyze" in kwargs:
-            warnings.warn(
-                "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results.",
-                DeprecationWarning,
-            )
-            analyze = kwargs["analyze"]
-
         exported_files = []
         if not export_folder:
             export_folder = self.working_directory

src/ansys/aedt/core/circuit.py

@@ -39,6 +39,7 @@
 from ansys.aedt.core.generic.file_utils import generate_unique_name
 from ansys.aedt.core.generic.file_utils import open_file
 from ansys.aedt.core.generic.file_utils import read_configuration_file
+from ansys.aedt.core.generic.general_methods import deprecate_argument
 from ansys.aedt.core.generic.general_methods import is_linux
 from ansys.aedt.core.generic.general_methods import pyaedt_function_handler
 from ansys.aedt.core.generic.settings import settings
@@ -1648,6 +1649,10 @@ def import_edb_in_circuit(self, input_dir):
     @pyaedt_function_handler(
         touchstone="input_file", probe_pins="tx_schematic_pins", probe_ref_pins="tx_schematic_differential_pins"
     )
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def create_tdr_schematic_from_snp(
         self,
         input_file,
@@ -1792,6 +1797,10 @@ def create_tdr_schematic_from_snp(
         return True, tdr_probe_names
 
     @pyaedt_function_handler(touchstone="input_file")
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def create_lna_schematic_from_snp(
         self,
         input_file,
@@ -1906,6 +1915,10 @@ def create_lna_schematic_from_snp(
         tx_refs="tx_schematic_differential_pins",
         rx_refs="rx_schematic_differentialial_pins",
     )
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def create_ami_schematic_from_snp(
         self,
         input_file,
@@ -2008,6 +2021,10 @@ def create_ami_schematic_from_snp(
         )
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def create_ibis_schematic_from_snp(
         self,
         input_file,
@@ -2122,6 +2139,10 @@ def create_ibis_schematic_from_snp(
         )
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def create_ibis_schematic_from_pins(
         self,
         ibis_tx_file,

src/ansys/aedt/core/generic/general_methods.py

@@ -25,6 +25,7 @@
 
 import datetime
 import difflib
+import functools
 from functools import update_wrapper
 import inspect
 import itertools
@@ -34,6 +35,7 @@
 import sys
 import time
 import traceback
+import warnings
 
 from ansys.aedt.core.aedt_logger import pyaedt_logger
 from ansys.aedt.core.generic.numbers import _units_assignment
@@ -235,6 +237,52 @@ def deprecate_kwargs(func_name, kwargs, aliases):
             kwargs[new] = kwargs.pop(alias)
 
 
+def deprecate_argument(arg_name: str, version: str = None, message: str = None, removed: bool = False):
+    """
+    Decorator to deprecate a specific argument (positional or keyword) in a function.
+
+    Parameters:
+        arg_name : str
+            The name of the deprecated argument.
+        version : str
+            The version in which the argument was removed.
+        message : str, optional
+            Custom deprecation message.
+        removed : bool
+            If ``True``, using the argument raises a TypeError.
+            If ``False``, a DeprecationWarning is issued.
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            sig = inspect.signature(func)
+            try:
+                bound_args = sig.bind_partial(*args, **kwargs)
+                bound_args.apply_defaults()
+            except TypeError:
+                # In case of incomplete binding (e.g. missing required args), skip
+                return func(*args, **kwargs)
+
+            if arg_name in bound_args.arguments:
+                msg_version = ""
+                if version:
+                    msg_version = f" in version {version}"
+                if removed:
+                    raise TypeError(
+                        message or f"Argument '{arg_name}' was removed{msg_version} and is no longer supported."
+                    )
+                else:
+                    warn_msg = message or f"Argument '{arg_name}' is deprecated and will be removed{msg_version}."
+                    warnings.warn(warn_msg, DeprecationWarning, stacklevel=2)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 def pyaedt_function_handler(direct_func=None, **deprecated_kwargs):
     """Provide an exception handler, logging mechanism, and argument converter for client-server communications.
 

src/ansys/aedt/core/q3d.py

@@ -32,6 +32,7 @@
 from ansys.aedt.core.generic.constants import MATRIXOPERATIONSQ2D
 from ansys.aedt.core.generic.constants import MATRIXOPERATIONSQ3D
 from ansys.aedt.core.generic.file_utils import generate_unique_name
+from ansys.aedt.core.generic.general_methods import deprecate_argument
 from ansys.aedt.core.generic.general_methods import pyaedt_function_handler
 from ansys.aedt.core.generic.numbers import decompose_variable_value
 from ansys.aedt.core.generic.settings import settings
@@ -2499,6 +2500,10 @@ def auto_assign_conductors(self):
         return True
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        arg_name="analyze",
+        message="The ``analyze`` argument will be removed in future versions. Analyze before exporting results.",
+    )
     def export_w_elements(self, analyze=False, export_folder=None):
         """Export all W-elements to files.