FEAT: args deprecation decorator

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,12 @@ def list_of_variations(self, setup=None, sweep=None):
                 return [""]
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def export_results(
         self,
+        analyze=False,
         export_folder=None,
         matrix_name="Original",
         matrix_type="S",
@@ -794,12 +799,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 +854,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,9 @@ 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(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def create_tdr_schematic_from_snp(
         self,
         input_file,
@@ -1792,6 +1796,9 @@ def create_tdr_schematic_from_snp(
         return True, tdr_probe_names
 
     @pyaedt_function_handler(touchstone="input_file")
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def create_lna_schematic_from_snp(
         self,
         input_file,
@@ -1906,6 +1913,9 @@ def create_lna_schematic_from_snp(
         tx_refs="tx_schematic_differential_pins",
         rx_refs="rx_schematic_differentialial_pins",
     )
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def create_ami_schematic_from_snp(
         self,
         input_file,
@@ -2008,6 +2018,9 @@ def create_ami_schematic_from_snp(
         )
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def create_ibis_schematic_from_snp(
         self,
         input_file,
@@ -2122,6 +2135,9 @@ def create_ibis_schematic_from_snp(
         )
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated 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,41 @@
             kwargs[new] = kwargs.pop(alias)
 
 
+def deprecate_argument(arg_name: str, message: str = None):
+    """
+    Decorator to deprecate a specific argument (positional or keyword) in a function.
+
+    Parameters:
+        arg_name : str
+            The name of the deprecated argument.
+        message : str, optional
+            Custom deprecation message.
+    """
+
+    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)
+
+            # once argument is definitely deprecated raise a TypeError instead of a warning
+            # raise TypeError(f"Argument '{arg_name}' is no longer supported.")
+            if arg_name in bound_args.arguments:
+                warn_msg = message or f"Argument '{arg_name}' is deprecated and will be removed in a future 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,9 @@ def auto_assign_conductors(self):
         return True
 
     @pyaedt_function_handler()
+    @deprecate_argument(
+        "analyze", "The ``analyze`` argument will be deprecated in future versions." "Analyze before exporting results."
+    )
     def export_w_elements(self, analyze=False, export_folder=None):
         """Export all W-elements to files.