feat: adding deprecation support for args and methods (#1261)

Co-authored-by: pyansys-ci-bot <pyansys.github.bot@ansys.com>

Author: RobPasMue

doc/changelog.d/1261.added.md

@@ -0,0 +1 @@
+feat: adding deprecation support for args and methods

src/ansys/geometry/core/connection/launcher.py

@@ -35,7 +35,7 @@
 )
 from ansys.geometry.core.connection.product_instance import prepare_and_start_backend
 from ansys.geometry.core.logger import LOG as logger
-from ansys.geometry.core.misc.checks import check_type
+from ansys.geometry.core.misc.checks import check_type, deprecated_argument
 
 try:
     import ansys.platform.instancemanagement as pypim
@@ -475,6 +475,8 @@ def launch_modeler_with_spaceclaim_and_pimlight(
     )
 
 
+@deprecated_argument(arg="log_level", alternative="server_log_level")
+@deprecated_argument(arg="logs_folder", alternative="server_logs_folder")
 def launch_modeler_with_geometry_service(
     product_version: int = None,
     host: str = "localhost",
@@ -600,6 +602,8 @@ def launch_modeler_with_geometry_service(
     )
 
 
+@deprecated_argument(arg="log_level", alternative="server_log_level")
+@deprecated_argument(arg="logs_folder", alternative="server_logs_folder")
 def launch_modeler_with_discovery(
     product_version: int = None,
     host: str = "localhost",
@@ -732,6 +736,8 @@ def launch_modeler_with_discovery(
     )
 
 
+@deprecated_argument(arg="log_level", alternative="server_log_level")
+@deprecated_argument(arg="logs_folder", alternative="server_logs_folder")
 def launch_modeler_with_spaceclaim(
     product_version: int = None,
     host: str = "localhost",

src/ansys/geometry/core/connection/product_instance.py

@@ -263,21 +263,13 @@ def prepare_and_start_backend(
     if os.name != "nt":  # pragma: no cover
         raise RuntimeError("Method 'prepare_and_start_backend' is only available on Windows.")
 
-    # Deprecation warnings... To be removed in release 0.7
+    # Deprecation behavior... To be removed in release 0.7
     if log_level is not None:  # pragma: no cover
-        LOG.warning(
-            "The 'log_level' parameter is deprecated. Please use 'server_log_level' instead."
-            " The 'log_level' parameter will be removed in the next minor release."
-            " Overriding 'server_log_level' with 'log_level' value for now..."
-        )
+        LOG.warning("Overriding 'server_log_level' with 'log_level' value for now...")
         server_log_level = log_level
 
     if logs_folder is not None:  # pragma: no cover
-        LOG.warning(
-            "The 'logs_folder' parameter is deprecated. Please use 'server_logs_folder' instead."
-            " The 'logs_folder' parameter will be removed in the next minor release."
-            " Overriding 'server_logs_folder' with 'logs_folder' value for now..."
-        )
+        LOG.warning("Overriding 'server_logs_folder' with 'logs_folder' value for now...")
         server_logs_folder = logs_folder
 
     port = _check_port_or_get_one(port)

src/ansys/geometry/core/designer/face.py

@@ -41,7 +41,11 @@
 from ansys.geometry.core.errors import GeometryRuntimeError, protect_grpc
 from ansys.geometry.core.math.point import Point3D
 from ansys.geometry.core.math.vector import UnitVector3D
-from ansys.geometry.core.misc.checks import ensure_design_is_active, min_backend_version
+from ansys.geometry.core.misc.checks import (
+    deprecated_method,
+    ensure_design_is_active,
+    min_backend_version,
+)
 from ansys.geometry.core.misc.measurements import DEFAULT_UNITS
 from ansys.geometry.core.shapes.box_uv import BoxUV
 from ansys.geometry.core.shapes.curves.trimmed_curve import TrimmedCurve
@@ -321,6 +325,33 @@ def normal(self, u: float = 0.5, v: float = 0.5) -> UnitVector3D:
             response = self._faces_stub.GetNormal(GetNormalRequest(id=self.id, u=u, v=v)).direction
             return UnitVector3D([response.x, response.y, response.z])
 
+    @deprecated_method(alternative="normal")
+    def face_normal(self, u: float = 0.5, v: float = 0.5) -> UnitVector3D:  # [deprecated-method]
+        """
+        Get the normal direction to the face at certain proportional UV coordinates.
+
+        Notes
+        -----
+        This method is deprecated. Use the ``normal`` method instead.
+
+        Parameters
+        ----------
+        u : float, default: 0.5
+            First coordinate of the 2D representation of a surface in UV space.
+            The default is ``0.5``, which is the center of the surface.
+        v : float, default: 0.5
+            Second coordinate of the 2D representation of a surface in UV space.
+            The default is ``0.5``, which is the center of the surface.
+
+        Returns
+        -------
+        UnitVector3D
+            :class:`UnitVector3D` object evaluated at the given U and V coordinates.
+            This :class:`UnitVector3D` object is perpendicular to the surface at the
+            given UV coordinates.
+        """
+        return self.normal(u, v)
+
     @protect_grpc
     @ensure_design_is_active
     def point(self, u: float = 0.5, v: float = 0.5) -> Point3D:
@@ -345,8 +376,7 @@ def point(self, u: float = 0.5, v: float = 0.5) -> Point3D:
         Returns
         -------
         Point3D
-            :class:`Point3D`
-            object evaluated at the given UV coordinates.
+            :class:`Point3D` object evaluated at the given UV coordinates.
         """
         try:
             return self.shape.evaluate_proportion(u, v).position
@@ -356,6 +386,31 @@ def point(self, u: float = 0.5, v: float = 0.5) -> Point3D:
             response = self._faces_stub.Evaluate(EvaluateRequest(id=self.id, u=u, v=v)).point
             return Point3D([response.x, response.y, response.z], DEFAULT_UNITS.SERVER_LENGTH)
 
+    @deprecated_method(alternative="point")
+    def face_point(self, u: float = 0.5, v: float = 0.5) -> Point3D:
+        """
+        Get a point of the face evaluated at certain proportional UV coordinates.
+
+        Notes
+        -----
+        This method is deprecated. Use the ``point`` method instead.
+
+        Parameters
+        ----------
+        u : float, default: 0.5
+            First coordinate of the 2D representation of a surface in UV space.
+            The default is ``0.5``, which is the center of the surface.
+        v : float, default: 0.5
+            Second coordinate of the 2D representation of a surface in UV space.
+            The default is ``0.5``, which is the center of the surface.
+
+        Returns
+        -------
+        Point3D
+            :class:`Point3D` object evaluated at the given UV coordinates.
+        """
+        return self.point(u, v)
+
     def __grpc_edges_to_edges(self, edges_grpc: List[GRPCEdge]) -> List[Edge]:
         """
         Transform a list of gRPC edge messages into actual ``Edge`` objects.

src/ansys/geometry/core/misc/__init__.py

@@ -41,6 +41,8 @@
     check_type,
     check_type_all_elements_in_iterable,
     check_type_equivalence,
+    deprecated_argument,
+    deprecated_method,
     min_backend_version,
 )
 from ansys.geometry.core.misc.measurements import DEFAULT_UNITS, Angle, Distance

src/ansys/geometry/core/misc/checks.py

@@ -20,6 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """Provides functions for performing common checks."""
+import warnings
+
 from beartype.typing import TYPE_CHECKING, Any, Iterable, Optional, Tuple, Union
 import numpy as np
 from pint import Unit
@@ -362,3 +364,65 @@ def wrapper(self, *args, **kwargs):
         return wrapper
 
     return backend_version_decorator
+
+
+def deprecated_method(alternative: Optional[str] = None, info: Optional[str] = None):
+    """
+    Decorate a method as deprecated.
+
+    Parameters
+    ----------
+    alternative : str, default: None
+        Alternative method to use. If provided, the warning message will
+        include the alternative method.
+    info : str, default: None
+        Additional information to include in the warning message.
+    """
+
+    def deprecated_decorator(method):
+
+        def wrapper(*args, **kwargs):
+            msg = f"The method '{method.__name__}' is deprecated."
+            if alternative:
+                msg += f" Use '{alternative}' instead."
+            if info:
+                msg += f" {info}"
+            warnings.warn(msg, DeprecationWarning)
+            return method(*args, **kwargs)
+
+        return wrapper
+
+    return deprecated_decorator
+
+
+def deprecated_argument(arg: str, alternative: Optional[str] = None, info: Optional[str] = None):
+    """
+    Decorate a method argument as deprecated.
+
+    Parameters
+    ----------
+    arg : str
+        Argument to mark as deprecated.
+    alternative : str, default: None
+        Alternative argument to use. If provided, the warning message will
+        include the alternative argument.
+    info : str, default: None
+        Additional information to include in the warning message.
+    """
+
+    def deprecated_decorator(method):
+
+        def wrapper(*args, **kwargs):
+            if arg in kwargs and kwargs[arg] is not None:
+                msg = f"The argument '{arg}' in '{method.__name__}' is deprecated."
+                if alternative:
+                    msg += f" Use '{alternative}' instead."
+                if info:
+                    msg += f" {info}"
+                warnings.warn(msg, DeprecationWarning)
+
+            return method(*args, **kwargs)
+
+        return wrapper
+
+    return deprecated_decorator

src/ansys/geometry/core/plotting/plotter.py

@@ -20,7 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """Provides plotting for various PyAnsys Geometry objects."""
-from ansys.tools.visualization_interface import Color, EdgePlot, MeshObjectPlot, Plotter
+from ansys.tools.visualization_interface import Color, EdgePlot, MeshObjectPlot
+from ansys.tools.visualization_interface import Plotter as PlotterInterface
 from ansys.tools.visualization_interface.backends.pyvista import PyVistaBackend
 from beartype.typing import Any, Dict, List, Optional, Union
 import numpy as np
@@ -35,10 +36,10 @@
 from ansys.geometry.core.math.frame import Frame
 from ansys.geometry.core.math.plane import Plane
 from ansys.geometry.core.plotting.widgets import ShowDesignPoints
-from ansys.geometry.core.sketch import Sketch
+from ansys.geometry.core.sketch.sketch import Sketch
 
 
-class GeometryPlotter(Plotter):
+class GeometryPlotter(PlotterInterface):
     """
     Plotter for PyAnsys Geometry objects.
 

tests/test_misc_checks.py

@@ -20,6 +20,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+import warnings
+
 import numpy as np
 import pytest
 
@@ -34,6 +36,8 @@
     check_pint_unit_compatibility,
     check_type,
     check_type_equivalence,
+    deprecated_argument,
+    deprecated_method,
     min_backend_version,
 )
 
@@ -266,3 +270,91 @@ def case_no_version(mock_object):
         match="The method 'case_no_version' requires a minimum Ansys release version of 24.2.0, but the current version used is 24.1.0 or lower.",  # noqa: E501
     ):
         case_no_version(mock_object)
+
+
+def test_deprecated_method_decorator():
+    """Test the deprecated method decorator."""
+
+    class MockObject:
+        def __init__(self):
+            self._grpc_client = None
+
+        @staticmethod
+        @deprecated_method()
+        def deprecated_method_no_input():
+            return True
+
+        @staticmethod
+        @deprecated_method(info="This is some extra info.")
+        def deprecated_method_with_info():
+            return True
+
+        @staticmethod
+        @deprecated_method(info="This is some extra info.", alternative="new_method")
+        def deprecated_method_with_info_and_alternate():
+            return True
+
+    mock_object = MockObject()
+
+    # Ensure that the method is deprecated
+    with pytest.deprecated_call(match="The method 'deprecated_method_no_input' is deprecated."):
+        mock_object.deprecated_method_no_input()
+
+    with pytest.deprecated_call(
+        match="The method 'deprecated_method_with_info' is deprecated. This is some extra info."
+    ):
+        mock_object.deprecated_method_with_info()
+
+    with pytest.deprecated_call(
+        match="The method 'deprecated_method_with_info_and_alternate' is deprecated."
+        " Use 'new_method' instead. This is some extra info."
+    ):
+        mock_object.deprecated_method_with_info_and_alternate()
+
+
+def test_deprecated_argument_decorator():
+    """Test the deprecated argument decorator."""
+
+    class MockObject:
+        def __init__(self):
+            self._grpc_client = None
+
+        @staticmethod
+        @deprecated_argument("dep_arg")
+        def deprecated_argument_no_input(dep_arg: str = None):
+            return True
+
+        @staticmethod
+        @deprecated_argument("dep_arg", info="This is some extra info.")
+        def deprecated_argument_with_info(dep_arg: str = None):
+            return True
+
+        @staticmethod
+        @deprecated_argument("dep_arg", info="This is some extra info.", alternative="alt_arg")
+        def deprecated_argument_with_info_and_alternate(dep_arg: str = None, alt_arg: str = None):
+            return True
+
+    mock_object = MockObject()
+
+    # Ensure that the argument is deprecated
+    with pytest.deprecated_call(
+        match="The argument 'dep_arg' in 'deprecated_argument_no_input' is deprecated."
+    ):
+        mock_object.deprecated_argument_no_input(dep_arg="test")
+
+    with pytest.deprecated_call(
+        match="The argument 'dep_arg' in 'deprecated_argument_with_info' is deprecated."
+        " This is some extra info."
+    ):
+        mock_object.deprecated_argument_with_info(dep_arg="test")
+
+    with pytest.deprecated_call(
+        match="The argument 'dep_arg' in 'deprecated_argument_with_info_and_alternate'"
+        " is deprecated. Use 'alt_arg' instead. This is some extra info."
+    ):
+        mock_object.deprecated_argument_with_info_and_alternate(dep_arg="test")
+
+    # Check that if we use the alternative argument, no warning is raised
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        mock_object.deprecated_argument_with_info_and_alternate(alt_arg="test")