FEAT: Add min version decorator (#5631)

Co-authored-by: Maxime Rey <[email protected]>
Co-authored-by: Giulia Malinverno <[email protected]>

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

@@ -27,6 +27,7 @@
 import os
 
 from ansys.aedt.core.application.analysis import Analysis
+from ansys.aedt.core.generic.checks import min_aedt_version
 from ansys.aedt.core.generic.configurations import Configurations
 from ansys.aedt.core.generic.constants import unit_converter
 from ansys.aedt.core.generic.general_methods import generate_unique_name
@@ -224,6 +225,7 @@ def components3d(self):
         return components_dict
 
     @pyaedt_function_handler(objects="assignment", export_path="output_file")
+    @min_aedt_version("2021.2")
     def plot(
         self,
         assignment=None,
@@ -280,23 +282,20 @@ def plot(
         :class:`ansys.aedt.core.generic.plot.ModelPlotter`
             Model Object.
         """
-        if self._aedt_version < "2021.2":
-            self.logger.warning("Plot is supported from AEDT 2021 R2.")
-        else:
-            return self.post.plot_model_obj(
-                objects=assignment,
-                show=show,
-                export_path=output_file,
-                plot_as_separate_objects=plot_as_separate_objects,
-                plot_air_objects=plot_air_objects,
-                force_opacity_value=force_opacity_value,
-                clean_files=clean_files,
-                view=view,
-                show_legend=show_legend,
-                dark_mode=dark_mode,
-                show_bounding=show_bounding,
-                show_grid=show_grid,
-            )
+        return self.post.plot_model_obj(
+            objects=assignment,
+            show=show,
+            export_path=output_file,
+            plot_as_separate_objects=plot_as_separate_objects,
+            plot_air_objects=plot_air_objects,
+            force_opacity_value=force_opacity_value,
+            clean_files=clean_files,
+            view=view,
+            show_legend=show_legend,
+            dark_mode=dark_mode,
+            show_bounding=show_bounding,
+            show_grid=show_grid,
+        )
 
     @pyaedt_function_handler(setup_name="setup", variation_string="variations")
     def export_mesh_stats(self, setup, variations="", mesh_path=None):
@@ -1145,6 +1144,7 @@ def flatten_3d_components(self, components=None, purge_history=True, password=No
         return True
 
     @pyaedt_function_handler(object_name="assignment")
+    @min_aedt_version("2023.2")
     def identify_touching_conductors(self, assignment=None):
         # type: (str) -> dict
         """Identify all touching components and group in a dictionary.
@@ -1161,10 +1161,7 @@ def identify_touching_conductors(self, assignment=None):
         dict
 
         """
-        if settings.aedt_version < "2023.2":  # pragma: no cover
-            self.logger.error("This method requires CPython and PyVista.")
-            return {}
-        if settings.aedt_version >= "2023.2" and self.design_type == "HFSS":  # pragma: no cover
+        if self.design_type == "HFSS":  # pragma: no cover
             nets_aedt = self.oboundary.IdentifyNets(True)
             nets = {}
             for net in nets_aedt[1:]:

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

@@ -68,7 +68,7 @@
 from ansys.aedt.core.generic.constants import AEDT_UNITS
 from ansys.aedt.core.generic.constants import unit_system
 from ansys.aedt.core.generic.data_handlers import variation_string_to_dict
-from ansys.aedt.core.generic.general_methods import GrpcApiError
+from ansys.aedt.core.generic.errors import GrpcApiError
 from ansys.aedt.core.generic.general_methods import check_and_download_file
 from ansys.aedt.core.generic.general_methods import generate_unique_name
 from ansys.aedt.core.generic.general_methods import inner_project_settings

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

@@ -50,7 +50,7 @@
 from ansys.aedt.core.generic.constants import SI_UNITS
 from ansys.aedt.core.generic.constants import _resolve_unit_system
 from ansys.aedt.core.generic.constants import unit_system
-from ansys.aedt.core.generic.general_methods import GrpcApiError
+from ansys.aedt.core.generic.errors import GrpcApiError
 from ansys.aedt.core.generic.general_methods import check_numeric_equivalence
 from ansys.aedt.core.generic.general_methods import is_array
 from ansys.aedt.core.generic.general_methods import is_number

src/ansys/aedt/core/emit_core/couplings.py

@@ -27,7 +27,7 @@
 This module provides for interacting with EMIT Analysis and Results windows.
 """
 
-import warnings
+from ansys.aedt.core.generic.checks import min_aedt_version
 
 
 class CouplingsEmit(object):
@@ -156,9 +156,12 @@ def update_link(self, coupling_name):
             self._odesign.UpdateLink(coupling_name)
 
     @property
+    @min_aedt_version("2022.2")
     def linkable_design_names(self):
         """List the available link names.
 
+        This property is only available in AEDT version 2022.2 or higher.
+
         Parameters
         ----------
         None
@@ -174,12 +177,7 @@ def linkable_design_names(self):
         >>> app = Emit("Apache with multiple links")
         >>> links = app.couplings.linkable_design_names
         """
-        desktop_version = self._desktop.GetVersion()[0:6]
-        if desktop_version >= "2022.2":
-            return self._odesign.GetAvailableLinkNames()
-        else:
-            warnings.warn("The function linkable_design_names() requires AEDT 2022 R2 or later.")
-            return []
+        return self._odesign.GetAvailableLinkNames()
 
     @property
     def cad_nodes(self):

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

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Provides functions for performing common checks."""
+
+from ansys.aedt.core.generic.errors import AEDTRuntimeError
+
+
+def min_aedt_version(min_version: str):
+    """Compare a minimum required version to the current AEDT version.
+
+    This decorator should only be used on methods where the associated object can reach the desktop instance.
+    Otherwise, there is no way to check version compatibility and an error is raised.
+
+    Parameters
+    ----------
+    min_version: str
+        Minimum AEDT version required by the method.
+        The value should follow the format YEAR.RELEASE, for example '2024.2'.
+
+    Raises
+    ------
+
+    AEDTRuntimeError
+        If the method version is higher than the AEDT version.
+    """
+
+    def fetch_odesktop_from_common_attributes_names(item):
+        attributes_to_check = ["odesktop", "_odesktop", "_desktop"]
+        for attribute in attributes_to_check:
+            odesktop = getattr(item, attribute, None)
+            if odesktop is not None:
+                return odesktop
+
+    def fetch_odesktop_from_private_app_attribute(item):
+        app = getattr(item, f"_{item.__class__.__name__}__app", None)
+        if app is not None:
+            return app.odesktop
+
+    def fetch_odesktop_from_desktop_class(item):
+        attributes_to_check = ["desktop_class", "_desktop_class"]
+        for attribute in attributes_to_check:
+            desktop_class = getattr(item, attribute, None)
+            if desktop_class is not None:
+                return desktop_class.odesktop
+
+    def aedt_version_decorator(method):
+        def wrapper(self, *args, **kwargs):
+            odesktop = (
+                fetch_odesktop_from_common_attributes_names(self)
+                or fetch_odesktop_from_private_app_attribute(self)
+                or fetch_odesktop_from_desktop_class(self)
+            )
+            if odesktop is None:
+                raise AEDTRuntimeError("The AEDT desktop object is not available.")
+
+            desktop_version = odesktop.GetVersion()
+            if desktop_version < min_version:
+                raise AEDTRuntimeError(
+                    f"The method '{method.__name__}' requires a minimum Ansys release version of "
+                    + f"{min_version}, but the current version used is {desktop_version}."
+                )
+            else:
+                return method(self, *args, **kwargs)
+
+        return wrapper
+
+    return aedt_version_decorator

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

@@ -32,7 +32,7 @@
 from ansys.aedt.core import __version__
 from ansys.aedt.core.application.variables import decompose_variable_value
 from ansys.aedt.core.generic.data_handlers import _arg2dict
-from ansys.aedt.core.generic.general_methods import GrpcApiError
+from ansys.aedt.core.generic.errors import GrpcApiError
 from ansys.aedt.core.generic.general_methods import generate_unique_folder_name
 from ansys.aedt.core.generic.general_methods import generate_unique_name
 from ansys.aedt.core.generic.general_methods import open_file

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

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Provide PyAEDT errors."""
+
+
+class GrpcApiError(RuntimeError):
+    """Exception raised for errors encountered while interacting with the gRPC API."""
+
+
+class MethodNotSupportedError(RuntimeError):
+    """Exception raised when attempting to call a method that is not supported."""
+
+
+class AEDTRuntimeError(RuntimeError):
+    """Exception raised for errors occurring during the runtime execution of AEDT scripts."""

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

@@ -47,6 +47,8 @@
 from ansys.aedt.core.aedt_logger import pyaedt_logger
 from ansys.aedt.core.generic.aedt_versions import aedt_versions
 from ansys.aedt.core.generic.constants import CSS4_COLORS
+from ansys.aedt.core.generic.errors import GrpcApiError
+from ansys.aedt.core.generic.errors import MethodNotSupportedError
 from ansys.aedt.core.generic.settings import inner_project_settings  # noqa: F401
 from ansys.aedt.core.generic.settings import settings
 import psutil
@@ -67,18 +69,6 @@
 ]
 
 
-class GrpcApiError(Exception):
-    """ """
-
-    pass
-
-
-class MethodNotSupportedError(Exception):
-    """ """
-
-    pass
-
-
 def _write_mes(mes_text):
     mes_text = str(mes_text)
     parts = [mes_text[i : i + 250] for i in range(0, len(mes_text), 250)]

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

@@ -34,7 +34,7 @@
 import time
 import types
 
-from ansys.aedt.core.generic.general_methods import GrpcApiError
+from ansys.aedt.core.generic.errors import GrpcApiError
 from ansys.aedt.core.generic.general_methods import _retry_ntimes
 from ansys.aedt.core.generic.general_methods import inclusion_list
 from ansys.aedt.core.generic.general_methods import settings

src/ansys/aedt/core/hfss3dlayout.py

@@ -34,6 +34,7 @@
 
 from ansys.aedt.core.application.analysis_3d_layout import FieldAnalysis3DLayout
 from ansys.aedt.core.application.analysis_hf import ScatteringMethods
+from ansys.aedt.core.generic.checks import min_aedt_version
 from ansys.aedt.core.generic.general_methods import generate_unique_name
 from ansys.aedt.core.generic.general_methods import open_file
 from ansys.aedt.core.generic.general_methods import parse_excitation_file
@@ -915,6 +916,7 @@ def export_touchstone_on_completion(self, export=True, output_dir=""):
         return True
 
     @pyaedt_function_handler()
+    @min_aedt_version("2025.1")
     def set_export_touchstone(
         self,
         file_format="TouchStone1.0",
@@ -995,9 +997,6 @@ def set_export_touchstone(
 
 
         """
-        if settings.aedt_version < "2025.1":
-            self.logger.warning("Touchstone export setup aborted. This method is available from AEDT 2025.1.")
-            return False
         preferences = "Planar EM\\"
         design_name = self.design_name
 

src/ansys/aedt/core/icepak.py

@@ -36,7 +36,7 @@
 from ansys.aedt.core.generic.data_handlers import _arg2dict
 from ansys.aedt.core.generic.data_handlers import _dict2arg
 from ansys.aedt.core.generic.data_handlers import random_string
-from ansys.aedt.core.generic.general_methods import GrpcApiError
+from ansys.aedt.core.generic.errors import GrpcApiError
 from ansys.aedt.core.generic.general_methods import generate_unique_name
 from ansys.aedt.core.generic.general_methods import open_file
 from ansys.aedt.core.generic.general_methods import pyaedt_function_handler

src/ansys/aedt/core/modeler/cad/component_array.py

@@ -27,6 +27,7 @@
 import os
 import re
 
+from ansys.aedt.core.generic.checks import min_aedt_version
 from ansys.aedt.core.generic.constants import AEDT_UNITS
 from ansys.aedt.core.generic.general_methods import _uname
 from ansys.aedt.core.generic.general_methods import pyaedt_function_handler
@@ -368,6 +369,7 @@ def delete(self):
         self.__app.component_array_names = list(self.__app.get_oo_name(self.__app.odesign, "Model"))
 
     @pyaedt_function_handler(array_path="output_file")
+    @min_aedt_version("2024.1")
     def export_array_info(self, output_file=None):  # pragma: no cover
         """Export array information to a CSV file.
 
@@ -379,12 +381,7 @@ def export_array_info(self, output_file=None):  # pragma: no cover
         References
         ----------
         >>> oModule.ExportArray
-
         """
-        if self.__app.settings.aedt_version < "2024.1":  # pragma: no cover
-            self.logger.warning(f"This feature is not available in {str(self.__app.settings.aedt_version)}.")
-            return False
-
         if not output_file:  # pragma: no cover
             output_file = os.path.join(self.__app.toolkit_directory, "array_info.csv")
         self.__app.omodelsetup.ExportArray(self.name, output_file)