update test and cheatsheet

doc/source/cheatsheet/cheat_sheet.qmd

@@ -75,12 +75,12 @@ ansys-mechanical -r 242 --port 10000 -g
 ## Manually connect to the Mechanical session
 ```{python}
 #| eval: false
-import ansys.mechanical.core as pymechanical
+from ansys.mechanical.core import connect_to_mechanical
 # Connect locally
-mechanical = pymechanical.Mechanical(port=10000)
+mechanical = connect_to_mechanical(port=10000)
           # Or
 # Connect remotely, to the IP address or hostname
-mechanical = pymechanical.Mechanical(
+mechanical = connect_to_mechanical(
   "192.168.0.1", port=10000
   )
 ```

src/ansys/mechanical/core/mechanical.py

@@ -2245,32 +2245,80 @@ def launch_mechanical(
 
 
 def connect_to_mechanical(
-    port=None,
     ip=None,
+    port=None,
     loglevel="ERROR",
     log_file=False,
     log_mechanical=None,
-    start_timeout=120,
+    connect_timeout=120,
     clear_on_connect=False,
-    cleanup_on_exit=True,
+    cleanup_on_exit=False,
     keep_connection_alive=True,
 ) -> Mechanical:
-    """Connect to an existing Mechanical server instance .
+    """Connect to an existing Mechanical server instance.
+
+    Parameters
+    ----------
+    ip : str, optional
+        IP address for connecting to an existing Mechanical instance. The
+        IP address defaults to ``"127.0.0.1"``.
+    port : int, optional
+        Port to listen on for an existing Mechanical instance. The default is ``None``,
+        in which case ``10000`` is used. You can override the
+        default behavior of this parameter with the
+        ``PYMECHANICAL_PORT=<VALID PORT>`` environment variable.
+    loglevel : str, optional
+        Level of messages to print to the console.
+        Options are:
+
+        - ``"WARNING"``: Prints only Ansys warning messages.
+        - ``"ERROR"``: Prints only Ansys error messages.
+        - ``"INFO"``: Prints all Ansys messages.
+
+        The default is ``WARNING``.
+    log_file : bool, optional
+        Whether to copy the messages to a file named ``logs.log``, which is
+        located where the Python script is executed. The default is ``False``.
+    log_mechanical : str, optional
+        Path to the output file on the local disk to write every script
+        command to. The default is ``None``. However, you might set
+        ``"log_mechanical='pymechanical_log.txt'"`` to write all commands that are
+        sent to Mechanical via PyMechanical to this file. You can then use these
+        commands to run a script within Mechanical without PyMechanical.
+    connect_timeout : float, optional
+        Maximum allowable time in seconds to connect to the Mechanical server.
+        The default is ``120``.
+    clear_on_connect : bool, optional
+        Whether to clear the Mechanical instance when connecting. The default is ``False``.
+        When ``True``, a fresh environment is provided when you connect to Mechanical.
+    cleanup_on_exit : bool, optional
+        Whether to exit Mechanical when Python exits. The default is ``False``.
+        When ``False``, Mechanical is not exited when the garbage for this Mechanical
+        instance is collected.
+    keep_connection_alive : bool, optional
+        Whether to keep the gRPC connection alive by running a background thread
+        and making dummy calls for remote connections. The default is ``True``.
+
+    Returns
+    -------
+    ansys.mechanical.core.mechanical.Mechanical
+        Instance of Mechanical.
 
     Examples
     --------
-    Connect to Mechanical server which is already running on
-    specific ip and port.
+    Connect to an existing Mechanical instance at IP address ``192.168.1.30`` on port
+    ``50001``..
 
 
-    >>> mech = connect_to_mechanical(ip='192.168.1.30', port=50001)
+    >>> from ansys.mechanical.core import connect_to_mechanical
+    >>> pymech = connect_to_mechanical(ip='192.168.1.30', port=50001)
     """
     return launch_mechanical(
         start_instance=False,
         loglevel=loglevel,
         log_file=log_file,
         log_mechanical=log_mechanical,
-        start_timeout=start_timeout,
+        start_timeout=connect_timeout,
         port=port,
         ip=ip,
         clear_on_connect=clear_on_connect,

tests/conftest.py

@@ -203,17 +203,6 @@ def rootdir():
     yield base.parent
 
 
-# @pytest.fixture()
-# def subprocess_pass_expected(pytestconfig):
-#     """Checks for conditions to see if scripts run in subprocess are expected to pass or not."""
-
-#     version = pytestconfig.getoption("ansys_version")
-#     if os.name != "nt" and int(version) < 251:
-#         yield False
-#     else:
-#         yield True
-
-
 @pytest.fixture()
 def disable_cli():
     ansys.mechanical.core.run.DRY_RUN = True
@@ -290,7 +279,7 @@ def connect_to_mechanical_instance(port=None, clear_on_connect=False):
     # ip needs to be passed or start instance takes precedence
     # typical for container scenarios use connect
     # and needs to be treated as remote scenarios
-    mechanical = pymechanical.launch_mechanical(
+    mechanical = pymechanical.connect_to_mechanical(
         ip=hostname, port=port, clear_on_connect=clear_on_connect, cleanup_on_exit=False
     )
     return mechanical