feat: deprecating product_version in favor of version (#1998)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>

Author: RobPasMue

doc/changelog.d/1998.added.md

@@ -0,0 +1 @@
+deprecating ``product_version`` in favor of ``version``

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
-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
@@ -488,8 +488,9 @@ def launch_modeler_with_spaceclaim_and_pimlight(
     )
 
 
+@deprecated_argument("product_version", "version", version="0.10.8", remove="0.13.0")
 def launch_modeler_with_geometry_service(
-    product_version: int = None,
+    version: str | int | None = None,
     host: str = "localhost",
     port: int = None,
     enable_trace: bool = False,
@@ -498,6 +499,7 @@ def launch_modeler_with_geometry_service(
     client_log_level: int = logging.INFO,
     server_logs_folder: str = None,
     client_log_file: str = None,
+    product_version: int = None,  # DEPRECATED: use `version` instead
     **kwargs: dict | None,
 ) -> "Modeler":
     """Start the Geometry service locally using the ``ProductInstance`` class.
@@ -509,7 +511,7 @@ def launch_modeler_with_geometry_service(
 
     Parameters
     ----------
-    product_version: int, optional
+    version: str | int, optional
         The product version to be started. Goes from v24.1 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -547,6 +549,8 @@ def launch_modeler_with_geometry_service(
     client_log_file : str, optional
         Sets the client's log file path. If nothing is defined,
         the client will log to the console.
+    product_version: int, optional
+        The product version to be started. Deprecated, use `version` instead.
     **kwargs : dict, default: None
         Placeholder to prevent errors when passing additional arguments that
         are not compatible with this method.
@@ -599,7 +603,7 @@ def launch_modeler_with_geometry_service(
 
     return prepare_and_start_backend(
         BackendType.WINDOWS_SERVICE,
-        product_version=product_version,
+        version=version,
         host=host,
         port=port,
         enable_trace=enable_trace,
@@ -609,11 +613,13 @@ def launch_modeler_with_geometry_service(
         client_log_level=client_log_level,
         server_logs_folder=server_logs_folder,
         client_log_file=client_log_file,
+        product_version=product_version,
     )
 
 
+@deprecated_argument("product_version", "version", version="0.10.8", remove="0.13.0")
 def launch_modeler_with_discovery(
-    product_version: int = None,
+    version: str | int | None = None,
     host: str = "localhost",
     port: int = None,
     api_version: ApiVersions = ApiVersions.LATEST,
@@ -623,6 +629,7 @@ def launch_modeler_with_discovery(
     server_log_level: int = 2,
     client_log_level: int = logging.INFO,
     client_log_file: str = None,
+    product_version: int = None,  # DEPRECATED: use `version` instead
     **kwargs: dict | None,
 ):
     """Start Ansys Discovery locally using the ``ProductInstance`` class.
@@ -634,7 +641,7 @@ def launch_modeler_with_discovery(
 
     Parameters
     ----------
-    product_version: int, optional
+    version: str | int, optional
         The product version to be started. Goes from v24.1 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -674,6 +681,8 @@ def launch_modeler_with_discovery(
     client_log_file : str, optional
         Sets the client's log file path. If nothing is defined,
         the client will log to the console.
+    product_version: int, optional
+        The product version to be started. Deprecated, use `version` instead.
     **kwargs : dict, default: None
         Placeholder to prevent errors when passing additional arguments that
         are not compatible with this method.
@@ -720,7 +729,7 @@ def launch_modeler_with_discovery(
 
     return prepare_and_start_backend(
         BackendType.DISCOVERY,
-        product_version=product_version,
+        version=version,
         host=host,
         port=port,
         enable_trace=False,
@@ -731,11 +740,13 @@ def launch_modeler_with_discovery(
         server_log_level=server_log_level,
         client_log_level=client_log_level,
         client_log_file=client_log_file,
+        product_version=product_version,
     )
 
 
+@deprecated_argument("product_version", "version", version="0.10.8", remove="0.13.0")
 def launch_modeler_with_spaceclaim(
-    product_version: int = None,
+    version: str | int | None = None,
     host: str = "localhost",
     port: int = None,
     api_version: ApiVersions = ApiVersions.LATEST,
@@ -745,6 +756,7 @@ def launch_modeler_with_spaceclaim(
     server_log_level: int = 2,
     client_log_level: int = logging.INFO,
     client_log_file: str = None,
+    product_version: int = None,  # DEPRECATED: use `version` instead
     **kwargs: dict | None,
 ):
     """Start Ansys SpaceClaim locally using the ``ProductInstance`` class.
@@ -756,7 +768,7 @@ def launch_modeler_with_spaceclaim(
 
     Parameters
     ----------
-    product_version: int, optional
+    version: str | int, optional
         The product version to be started. Goes from v24.1 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -796,6 +808,8 @@ def launch_modeler_with_spaceclaim(
     client_log_file : str, optional
         Sets the client's log file path. If nothing is defined,
         the client will log to the console.
+    product_version: int, optional
+        The product version to be started. Deprecated, use `version` instead.
     **kwargs : dict, default: None
         Placeholder to prevent errors when passing additional arguments that
         are not compatible with this method.
@@ -842,7 +856,7 @@ def launch_modeler_with_spaceclaim(
 
     return prepare_and_start_backend(
         BackendType.SPACECLAIM,
-        product_version=product_version,
+        version=version,
         host=host,
         port=port,
         enable_trace=False,
@@ -853,103 +867,13 @@ def launch_modeler_with_spaceclaim(
         server_log_level=server_log_level,
         client_log_level=client_log_level,
         client_log_file=client_log_file,
+        product_version=product_version,
     )
 
 
-def _launch_pim_instance(
-    is_pim_light: bool,
-    product_name: str,
-    product_platform: str | None = None,
-    product_version: str | None = None,
-    client_log_level: int = logging.INFO,
-    client_log_file: str | None = None,
-):
-    """
-    Start `PyPIM <https://github.com/ansys/pypim>`_ using the PIM API.
-
-    When calling this method, you must ensure that you are in an
-    environment where PyPIM is configured. You can use the
-    :func:`pypim.is_configured <ansys.platform.instancemanagement.is_configured>`
-    method to check if it is configured.
-
-    Parameters
-    ----------
-    is_pim_light : bool
-        Whether PIM Light is being used. For example, whether PIM is
-        running on a local machine.
-    product_name : str
-        Name of the service to run.
-    product_platform : str, default: None
-        Platform on which the service will run. **Specific for Ansys Lab**.
-        This parameter is used to specify the operating system on which the
-        Geometry service will run. The possible values are:
-
-        * ``"windows"``: The Geometry service runs on a Windows machine.
-        * ``"linux"``: The Geometry service runs on a Linux machine.
-
-    product_version : str, default: None
-        Version of the service to run.
-    client_log_level : int, default: logging.INFO
-        Log level for the client. The default is ``logging.INFO``.
-    client_log_file : str, default: None
-        Path to the log file for the client. The default is ``None``,
-        in which case the client logs to the console.
-
-    Returns
-    -------
-    ansys.geometry.core.modeler.Modeler
-        Instance of the Geometry service.
-    """
-    from ansys.geometry.core.modeler import Modeler
-
-    check_type(product_version, (type(None), str))
-
-    if not _HAS_PIM:  # pragma: no cover
-        raise ModuleNotFoundError(
-            "The package 'ansys-platform-instancemanagement' is required to use this function."
-        )
-
-    # Platform is used mostly for Ansys Lab purposes. If product_version is defined, use it.
-    # Higher priority is given to product_version.
-    if product_platform:  # pragma: no cover
-        if product_version:
-            LOG.warning(
-                "The 'product_platform' parameter is not used when 'product_version' is defined."
-            )
-        else:
-            product_version = product_platform
-
-    # If PIM Light is being used and PyPIM configuration is not defined... use defaults.
-    if is_pim_light and not os.environ.get("ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG", None):
-        os.environ["ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG"] = pygeom_defaults.DEFAULT_PIM_CONFIG
-        pop_out = True
-    else:
-        pop_out = False
-
-    # Perform PyPIM connection
-    pim = pypim.connect()
-    instance = pim.create_instance(product_name=product_name, product_version=product_version)
-    instance.wait_for_ready()
-    channel = instance.build_grpc_channel(
-        options=[
-            ("grpc.max_receive_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
-        ]
-    )
-
-    # If the default PyPIM configuration was used... remove
-    if pop_out:
-        os.environ.pop("ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG")
-
-    return Modeler(
-        channel=channel,
-        remote_instance=instance,
-        logging_level=client_log_level,
-        logging_file=client_log_file,
-    )
-
-
+@deprecated_argument("product_version", "version", version="0.10.8", remove="0.13.0")
 def launch_modeler_with_core_service(
-    product_version: int = None,
+    version: str | int | None = None,
     host: str = "localhost",
     port: int = None,
     enable_trace: bool = False,
@@ -958,6 +882,7 @@ def launch_modeler_with_core_service(
     client_log_level: int = logging.INFO,
     server_logs_folder: str = None,
     client_log_file: str = None,
+    product_version: int = None,  # DEPRECATED: use `version` instead
     **kwargs: dict | None,
 ) -> "Modeler":
     """Start the Geometry Core service locally using the ``ProductInstance`` class.
@@ -969,7 +894,7 @@ def launch_modeler_with_core_service(
 
     Parameters
     ----------
-    product_version: int, optional
+    version: str | int, optional
         The product version to be started. Goes from v25.2 to
         the latest. Default is ``None``.
         If a specific product version is requested but not installed locally,
@@ -1007,6 +932,8 @@ def launch_modeler_with_core_service(
     client_log_file : str, optional
         Sets the client's log file path. If nothing is defined,
         the client will log to the console.
+    product_version: int, optional
+        The product version to be started. Deprecated, use `version` instead.
     **kwargs : dict, default: None
         Placeholder to prevent errors when passing additional arguments that
         are not compatible with this method.
@@ -1059,7 +986,7 @@ def launch_modeler_with_core_service(
 
     return prepare_and_start_backend(
         BackendType.LINUX_SERVICE,
-        product_version=product_version,
+        version=version,
         host=host,
         port=port,
         enable_trace=enable_trace,
@@ -1070,4 +997,97 @@ def launch_modeler_with_core_service(
         server_logs_folder=server_logs_folder,
         client_log_file=client_log_file,
         specific_minimum_version=252,
+        product_version=product_version,
+    )
+
+
+def _launch_pim_instance(
+    is_pim_light: bool,
+    product_name: str,
+    product_platform: str | None = None,
+    product_version: str | None = None,
+    client_log_level: int = logging.INFO,
+    client_log_file: str | None = None,
+):
+    """
+    Start `PyPIM <https://github.com/ansys/pypim>`_ using the PIM API.
+
+    When calling this method, you must ensure that you are in an
+    environment where PyPIM is configured. You can use the
+    :func:`pypim.is_configured <ansys.platform.instancemanagement.is_configured>`
+    method to check if it is configured.
+
+    Parameters
+    ----------
+    is_pim_light : bool
+        Whether PIM Light is being used. For example, whether PIM is
+        running on a local machine.
+    product_name : str
+        Name of the service to run.
+    product_platform : str, default: None
+        Platform on which the service will run. **Specific for Ansys Lab**.
+        This parameter is used to specify the operating system on which the
+        Geometry service will run. The possible values are:
+
+        * ``"windows"``: The Geometry service runs on a Windows machine.
+        * ``"linux"``: The Geometry service runs on a Linux machine.
+
+    product_version : str, default: None
+        Version of the service to run.
+    client_log_level : int, default: logging.INFO
+        Log level for the client. The default is ``logging.INFO``.
+    client_log_file : str, default: None
+        Path to the log file for the client. The default is ``None``,
+        in which case the client logs to the console.
+
+    Returns
+    -------
+    ansys.geometry.core.modeler.Modeler
+        Instance of the Geometry service.
+    """
+    from ansys.geometry.core.modeler import Modeler
+
+    check_type(product_version, (type(None), str))
+
+    if not _HAS_PIM:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "The package 'ansys-platform-instancemanagement' is required to use this function."
+        )
+
+    # Platform is used mostly for Ansys Lab purposes. If product_version is defined, use it.
+    # Higher priority is given to product_version.
+    if product_platform:  # pragma: no cover
+        if product_version:
+            LOG.warning(
+                "The 'product_platform' parameter is not used when 'product_version' is defined."
+            )
+        else:
+            product_version = product_platform
+
+    # If PIM Light is being used and PyPIM configuration is not defined... use defaults.
+    if is_pim_light and not os.environ.get("ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG", None):
+        os.environ["ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG"] = pygeom_defaults.DEFAULT_PIM_CONFIG
+        pop_out = True
+    else:
+        pop_out = False
+
+    # Perform PyPIM connection
+    pim = pypim.connect()
+    instance = pim.create_instance(product_name=product_name, product_version=product_version)
+    instance.wait_for_ready()
+    channel = instance.build_grpc_channel(
+        options=[
+            ("grpc.max_receive_message_length", pygeom_defaults.MAX_MESSAGE_LENGTH),
+        ]
+    )
+
+    # If the default PyPIM configuration was used... remove
+    if pop_out:
+        os.environ.pop("ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG")
+
+    return Modeler(
+        channel=channel,
+        remote_instance=instance,
+        logging_level=client_log_level,
+        logging_file=client_log_file,
     )