support variables in script; change argument release to version (#143)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: franknli

doc/changelog.d/143.documentation.md

@@ -0,0 +1 @@
+support variables in script; change argument release to version

doc/source/getting-started.rst

@@ -2,7 +2,7 @@ Getting started
 ###############
 
 To run PyWorkbench, you must have a licensed copy of `Workbench
-<https://www.ansys.com/products/ansys-workbench>`_ of release 24.2 or above.
+<https://www.ansys.com/products/ansys-workbench>`_ of version 24.2 or later.
 
 .. grid:: 2
 

doc/source/user-guide.rst

@@ -58,7 +58,7 @@ This code launches a server on a remote Windows machine with valid user credenti
     wb = launch_workbench(host=host, username=username, password=password)
 
 Other options for the ``launch_workbench()`` function include specifying a particular
-Workbench release to launch, whether to launch in UI mode, and specifying working directories
+Workbench version to launch, whether to launch in UI mode, and specifying working directories
 on the server and/or the client instead of using the default directories:
 
 .. code-block:: python
@@ -67,7 +67,7 @@ on the server and/or the client instead of using the default directories:
 
     wb = launch_workbench(
         show_gui=False,
-        release="242",
+        version="251",
         server_workdir="path_to_a_dir_on_server",
         client_workdir="path_to_a_dir_on_client",
     )
@@ -153,7 +153,7 @@ This client script downloads all files with ``.out`` extensions from the server'
 
 There is a special client method to upload a data file from the Ansys
 `example-data <https://github.com/ansys/example-data/raw/master/pyworkbench>`_ repository
-directly to the Workbench server. You should specify the file path relative to the
+directly to the Workbench server. You should specify the path relative to the
 ``pyworkbench`` folder in the ``example-data`` repository:
 
 .. code-block:: python

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -6,3 +6,4 @@
 Workbench
 PyMechanical
 PyFluent
+PySherlock

src/ansys/workbench/core/public_api.py

@@ -74,8 +74,8 @@ class LaunchWorkbench(ClientWrapper):
     ----------
     show_gui : bool, default: True
         Weather to launch Workbench in UI mode.
-    release : str, default: "242"
-        Workbench release to launch.
+    version : str, default: None
+        Workbench version to launch. It must be a 3-digit version that is "242" or later.
     client_workdir : str, default: None
         Path to a writable directory on the client computer. The default is ``None``,
         in which case the system temp directory is used.
@@ -95,7 +95,7 @@ class LaunchWorkbench(ClientWrapper):
     Raises
     ------
     Exception
-        If the Ansys release number is invalid.
+        If the Ansys version number is invalid.
 
     Examples
     --------
@@ -108,7 +108,7 @@ class LaunchWorkbench(ClientWrapper):
     def __init__(
         self,
         show_gui=True,
-        release="242",
+        version="242",
         client_workdir=None,
         server_workdir=None,
         host=None,
@@ -119,18 +119,18 @@ def __init__(
         self._process_id = -1
 
         if (
-            len(release) != 3
-            or not release.isdigit()
-            or release[0] not in ["2", "3"]
-            or release[2] not in ["1", "2"]
+            len(version) != 3
+            or not version.isdigit()
+            or version[0] not in ["2", "3"]
+            or version[2] not in ["1", "2"]
         ):
-            raise Exception("Invalid ANSYS release: " + release)
-        port = self.__launch_server(show_gui, host, release, server_workdir, username, password)
+            raise Exception("Invalid ANSYS version: " + version)
+        port = self.__launch_server(show_gui, host, version, server_workdir, username, password)
         if port is None or port <= 0:
             raise Exception("Filed to launch Ansys Workbench service.")
         super().__init__(port, client_workdir, host)
 
-    def __launch_server(self, show_gui, host, release, server_workdir, username, password):
+    def __launch_server(self, show_gui, host, version, server_workdir, username, password):
         """Launch a Workbench server on the local or a remote Windows machine."""
         try:
             if host is None:
@@ -146,11 +146,11 @@ def __launch_server(self, show_gui, host, release, server_workdir, username, pas
 
             install_path = None
             for ev in self._wmi_connection.Win32_Environment():
-                if ev.Name == "AWP_ROOT" + release:
+                if ev.Name == "AWP_ROOT" + version:
                     install_path = ev.VariableValue
                     break
             if install_path is None:
-                install_path = "C:/Program Files/Ansys Inc/v" + release
+                install_path = "C:/Program Files/Ansys Inc/v" + version
                 logging.warning(
                     "Ansys installation is not found. Assume the default location: " + install_path
                 )
@@ -260,7 +260,7 @@ def exit(self):
 
 def launch_workbench(
     show_gui=True,
-    release="242",
+    version=None,
     client_workdir=None,
     server_workdir=None,
     host=None,
@@ -276,8 +276,8 @@ def launch_workbench(
     ----------
     show_gui : bool, default: True
         Weather to launch Workbench in UI mode.
-    release : str, default: "251"
-        Workbench release to launch.
+    version : str, default: None
+        Workbench version to launch. It must be a 3-digit version that is "242" or later.
     client_workdir : str, default: None
         Path to a writable directory on the client computer. The default is ``None``,
         in which case the system temp directory is used.
@@ -308,7 +308,7 @@ def launch_workbench(
 
     """
     return LaunchWorkbench(
-        show_gui, release, client_workdir, server_workdir, host, username, password
+        show_gui, version, client_workdir, server_workdir, host, username, password
     )
 
 

src/ansys/workbench/core/workbench_client.py

@@ -28,6 +28,7 @@
 import logging.handlers
 from logging.handlers import WatchedFileHandler
 import os
+import re
 
 import grpc
 import tqdm
@@ -102,7 +103,7 @@ def set_console_log_level(self, log_level):
         Parameters
         ----------
         log_level : str, default: "error"
-            Level of logging. Options are "critical" "debug", "error", "info", and "warning".
+            Level of logging. Options are "critical", "debug", "error", "info", and "warning".
         """
         self.__log_console_handler.setLevel(WorkbenchClient.__to_python_log_level(log_level))
 
@@ -135,15 +136,18 @@ def reset_log_file(self):
     __log_file_handler = None
     __log_console_handler = None
 
-    def run_script_string(self, script_string, log_level="error"):
+    def run_script_string(self, script_string, args=None, log_level="error"):
         """Run a script as given in the input string on the server.
 
         Parameters
         ----------
         script_string : str
             String containing the content of the script to run.
+        args : dictionary of script variable names and values
+            Variables in the script specified as $$varname%%50%% will be converted to variable
+            values or use the default value - 50 in the example.
         log_level : str, default: "error"
-            Level of logging. Options are "critical" "debug", "error", "info", and "warning".
+            Level of logging. Options are "critical", "debug", "error", "info", and "warning".
 
         Returns
         -------
@@ -162,8 +166,22 @@ def run_script_string(self, script_string, log_level="error"):
         """
         if not self._is_connected():
             logging.error("Workbench client is not yet connected to a server.")
+            return None
+        updated_script_string = script_string
+        if args and len(args) > 0:
+            if any(not re.match(r"^\w+$", arg) for arg in args.keys()):
+                logging.error("script argument name contains illegal character.")
+                return None
+            for arg_name in args:
+                updated_script_string = re.sub(
+                    r"\$\$" + arg_name + r"%%((?!%%).)*%%",
+                    str(args[arg_name]),
+                    updated_script_string,
+                )
+        updated_script_string = re.sub(r"\$\$\w+%%(((?!%%).)*)%%", r"\1", updated_script_string)
         request = wb.RunScriptRequest(
-            content=script_string, log_level=WorkbenchClient.__to_server_log_level(log_level)
+            content=updated_script_string,
+            log_level=WorkbenchClient.__to_server_log_level(log_level),
         )
         for response in self.stub.RunScript(request):
             if response.log and response.log.messages and len(response.log.messages) > 0:
@@ -177,16 +195,19 @@ def run_script_string(self, script_string, log_level="error"):
                     logging.info("The script has finisished.")
                     return json.loads(response.result.result)
 
-    def run_script_file(self, script_file_name, log_level="error"):
+    def run_script_file(self, script_file_name, args=None, log_level="error"):
         """Run a script file on the server.
 
         Parameters
         ----------
         script_file_name : str
             Name of the script file to run. The script file should be located in the client
             working directory
+        args : dictionary of script variable names and values
+            Variables in the script specified as $$varname%%50%% will be converted to variable
+            values or use the default value - 50 in the example.
         log_level : str, default: "error"
-            Level of logging. Options are "critical" "debug", "error", "info", and "warning".
+            Level of logging. Options are "critical", "debug", "error", "info", and "warning".
 
         Returns
         -------
@@ -195,10 +216,11 @@ def run_script_file(self, script_file_name, log_level="error"):
         """
         if not self._is_connected():
             logging.error("Workbench client is not yet connected to a server")
+            return None
         script_path = os.path.join(self.workdir, script_file_name)
         with open(script_path, encoding="utf-8-sig") as sf:
             script_string = sf.read()
-        return self.run_script_string(script_string, log_level)
+        return self.run_script_string(script_string, args, log_level)
 
     def upload_file(self, *file_list, show_progress=True):
         """Upload one or more files from the client to the server.
@@ -218,6 +240,7 @@ def upload_file(self, *file_list, show_progress=True):
         """
         if not self._is_connected():
             logging.error("Workbench client is not yet connected to a server.")
+            return
         requested = []
         for file_pattern in file_list:
             if "*" in file_pattern or "?" in file_pattern:
@@ -289,6 +312,7 @@ def upload_file_from_example_repo(self, relative_file_path, show_progress=True):
         """
         if not self._is_connected():
             logging.error("Workbench client is not yet connected to a server.")
+            return
         downloaded = ExampleData.download(relative_file_path, self.workdir)
         self.upload_file(downloaded, show_progress=show_progress)
 
@@ -315,6 +339,7 @@ def download_file(self, file_name, show_progress=True, target_dir=None):
         """
         if not self._is_connected():
             logging.error("Workbench client is not yet connected to a server.")
+            return None
         request = wb.DownloadFileRequest(file_name=file_name)
         file_name = file_name.replace("*", "_").replace("?", "_")
         td = target_dir
@@ -406,7 +431,7 @@ def __to_server_log_level(log_level):
         Parameters
         ----------
         log_level : str
-            Level of logging. Options are "critical" "debug", "error", "info", and "warning".
+            Level of logging. Options are "critical", "debug", "error", "info", and "warning".
 
         Returns
         -------

tests/test_launch_workbench.py

@@ -34,7 +34,7 @@ def workbench():
     """Launch workbench."""
     workdir = pathlib.Path(__file__).parent
     wb = launch_workbench(
-        release="241",
+        version="241",
         server_workdir=str(workdir.absolute()),
         client_workdir=str(workdir.absolute()),
     )

tests/test_workbench_client.py

@@ -156,10 +156,6 @@ def test_run_script_file(mock_workbench_service_stub):
     assert mock_stub.RunScript.call_count == 1
     assert mock_response.result.result == "{'result': 'success'}"
 
-    client._disconnect()
-    with pytest.raises(Exception):
-        client.run_script_file(script_dir / "cooled_turbine_blade.py")
-
 
 def test_upload_file(mock_workbench_service_stub):
     """Test the upload_file method."""