Feat/context manager (#67)

README.rst

@@ -110,7 +110,7 @@ must be ``None``, other parameters can be optionally specified.:
 
     from ansys.optislang.core import Optislang
     osl = Optislang()
-    osl.shutdown()
+    osl.dispose()
 
 Connect to a remote optiSLang server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -125,7 +125,7 @@ related to the execution of the new optiSLang server are ignored.:
     host = "127.0.0.1"
     port = 5310
     osl = Optislang(host=host, port=port)
-    osl.shutdown()
+    osl.dispose()
 
 Basic usage
 ~~~~~~~~~~~
@@ -137,7 +137,7 @@ Basic usage
     file_path = r"C:\Users\Username\my_scripts\myscript.py"
     osl.run_python_file(path=script_path)
     osl.save_copy("MyNewProject.opf")
-    osl.shutdown()
+    osl.dispose()
 
 License and acknowledgments
 ---------------------------

doc/source/getting_started/index.rst

@@ -71,7 +71,7 @@ Verify installation
     >>> from ansys.optislang.core import Optislang
     >>> osl = Optislang()
     >>> print(osl)
-    >>> osl.shutdown()
+    >>> osl.dispose()
 
 If you see a response from the server, congratulations, you're ready
 to get started using OptiSLang as a service. For details regarding the

doc/source/user_guide/functions.rst

@@ -1,7 +1,8 @@
 .. _ref_functions:
 
+===========
 Basic usage
------------
+===========
 In order to start project, use :func:`start <ansys.optislang.core.optislang.Optislang.start>`
 (example :ref:`ref_simple_calculator` can be used):
 
@@ -37,3 +38,10 @@ Or via running specific requests:
     print(f'Location: {osl.get_project_location()}')
     print(f'Name: {osl.get_project_name()}')
     print(f'Status: {osl.get_project_status()}')
+
+When the :class:`Optislang() <ansys.optislang.core.optislang.Optislang>` instance is no longer 
+needed, terminate connection with optiSLang server by running:
+
+.. code:: python
+
+    osl.dispose()

doc/source/user_guide/index.rst

@@ -35,13 +35,27 @@ by the ``project_path`` parameter of the
     path = os.getcwd()
     file_name = 'test_optislang.opf'
     osl = Optislang(project_path = os.path.join(path, file_name))
-    osl.shutdown()
+    osl.dispose()
 
 
 If the project file exists, it is opened; otherwise, a new project file is created on the specified 
-path. Please note that the :func:`shutdown() <ansys.optislang.core.optislang.Optislang.shutdown>` 
-function should be executed when the :class:`Optislang <ansys.optislang.core.optislang.Optislang>` 
-instance is no more needed.
+path. Please note that :class:`Optislang <ansys.optislang.core.optislang.Optislang>` 
+instance should be always gracefully terminated when it's no longer in use by 
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` method. OptiSLang server may be
+optionally terminated by :func:`shutdown() <ansys.optislang.core.optislang.Optislang.shutdown>` 
+(this must be done before :func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>`
+method and it's not needed when started with default parameter ``shutdown_on_finished=True``).
+
+
+Difference in these termination methods is that method
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` only terminates connection
+with optiSLang server, method
+:func:`shutdown() <ansys.optislang.core.optislang.Optislang.shutdown>` sends command
+to terminate server, which is necessary when (server is started locally by instance of
+:class:`Optislang <ansys.optislang.core.optislang.Optislang>` with parameter 
+``shutdown_on_finished=False`` or connected to a remote optiSLang server) AND termination of optiSLang
+server is requested. 
+
 
 The :class:`Optislang <ansys.optislang.core.Optislang>` class provides several functions which 
 enable to control or query the project. The following example shows how to open an existing project 
@@ -55,7 +69,7 @@ and run it using the :func:`start() <ansys.optislang.core.optislang.Optislang.st
     project_path = examples.get_files('simple_calculator')[1]
     osl = Optislang(project_path = project_path)
     osl.start()
-    osl.shutdown()
+    osl.dispose()
 
 Currently, the capabilities provided by the ``ansys-optislang-core`` library are limited. 
 However, this can be overcome using the 

doc/source/user_guide/launch.rst

@@ -1,7 +1,20 @@
 .. _ref_launch:
 
+=====================================
 Initial setup and launching optiSLang
--------------------------------------
+=====================================
+Instance of
+:class:`Optislang <ansys.optislang.core.optislang.Optislang>` can either launch optiSLang server
+locally or it may connect to already running optiSLang server. This instance should be terminated 
+gracefully when it's no longer in use by calling
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` method. Therefore, it is 
+recommended to use instance of :class:`Optislang <ansys.optislang.core.optislang.Optislang>` 
+as a context manager, that will execute 
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` method automatically even
+when error is raised.
+
+Launching optiSLang locally
+---------------------------
 In order to run, ``ansys.optislang.core`` needs to know the location of the optiSLang.
 Most of the time this can be automatically determined, but non-standard installs needs 
 to provide the location of optiSLang. You can start optiSLang by running:
@@ -11,7 +24,7 @@ to provide the location of optiSLang. You can start optiSLang by running:
     from ansys.optislang.core import Optislang
     osl = Optislang()
     print(osl)
-    osl.shutdown()
+    osl.dispose()
 
 
 List of all automatically detected, supported executables of optiSLang can be obtained by running:
@@ -30,7 +43,7 @@ from list preceding, launch :class:`Optislang <ansys.optislang.core.optislang.Op
     from ansys.optislang.core import Optislang
     osl = Optislang(executable = r'C:\\Program Files\\Dynardo\\Ansys optiSLang\\2023 R1\\optislang.com')
     print(osl)
-    osl.shutdown()
+    osl.dispose()
 
 In order to open specific project or create new one, launch 
 :class:`Optislang <ansys.optislang.core.optislang.Optislang>` with parameter
@@ -46,7 +59,36 @@ In order to open specific project or create new one, launch
 
     osl = Optislang(project_path = os.path.join(path, project_name))
     print(osl)
+    osl.dispose()
+
+Keep optiSLang server running
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Default setting of optiSLang server is ``shutdown_on_finished=True``. This means that optiSLang
+server is terminated automatically after 
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` method was called. 
+If user wishes to keep optiSLang server running even after disposing
+:class:`Optislang <ansys.optislang.core.optislang.Optislang>` instance, parameter 
+``shutdown_on_finished=False`` must be used when creating new instance.
+
+.. code:: python
+
+    from ansys.optislang.core import Optislang
+
+    osl = Optislang(shutdown_on_finished=False)
+    print(osl)
+    osl.dispose()
+
+In order to terminate optiSLang server launched this way, use
+:func:`shutdown() <ansys.optislang.core.optislang.Optislang.shutdown>` method:
+
+.. code:: python
+
+    from ansys.optislang.core import Optislang
+
+    osl = Optislang(shutdown_on_finished=False)
+    print(osl)
     osl.shutdown()
+    osl.dispose()
 
 Connect to a remote instance of optiSLang
 -----------------------------------------
@@ -56,7 +98,51 @@ related to the execution of the new optiSLang server are ignored.
 
 .. code:: python
 
-     from ansys.optislang.core import Optislang
-     osl = Optislang(host = "127.0.0.1", port = 49690)
+     from ansys.optislang.core import Optislang, OslServerProcess
+     import time
+
+     server_process = OslServerProcess(shutdown_on_finished=False, logger=logger)
+     server_process.start()
+     time.sleep(5)  # wait for launching of server process
+
+     # connect to optiSLang server and terminate connection afterward
+     osl = Optislang(host = "127.0.0.1", port = 5310)
+     print(osl)
+     osl.dispose()
+
+     # connect to optiSLang server and terminate server afterward
+     osl = Optislang(host = "127.0.0.1", port = 5310)
      print(osl)
      osl.shutdown()
+     osl.dispose()
+
+Context manager
+---------------
+It is recommended to use 
+:class:`Optislang() <ansys.optislang.core.optislang.Optislang>` as a context manager. Main advantage
+of this approach is that instance of :class:`Optislang() <ansys.optislang.core.optislang.Optislang>`
+and connection to optiSLang server will be terminated gracefully even if an error occurs by calling
+:func:`dispose() <ansys.optislang.core.optislang.Optislang.dispose>` method automatically.
+
+.. code:: python
+
+    from ansys.optislang.core import Optislang
+    with Optislang() as osl:
+        print(osl)
+        osl.start()
+
+.. note::
+
+    When instance of :class:`Optislang <ansys.optislang.core.optislang.Optislang>` is started
+    with argument ``shutdown_on_finished=False`` or connected to optiSLang server started with
+    such setting, default behaviour is to terminate connection and keep optiSLang server running.
+    In order to terminate optiSLang server, method 
+    :func:`shutdown() <ansys.optislang.core.optislang.Optislang.shutdown>` has to be used.
+
+    .. code:: python
+
+        from ansys.optislang.core import Optislang
+        with Optislang(shutdown_on_finished=False) as osl:
+            print(osl)
+            osl.start()
+            osl.shutdown()

doc/source/user_guide/run_python.rst

@@ -1,7 +1,8 @@
 .. _ref_run_python:
 
+============================================
 Executing commands from optiSLang Python API
------------------------------------------------
+============================================
 When optiSLang is active, you can send individual python commands to it as a genuine a
 Python class. For example, if you want to get general information about sensitivity actor, 
 you would call:
@@ -12,7 +13,7 @@ you would call:
 
     osl = Optislang()
     print(osl.run_python_script("""help(actors.SensitivityActor)"""))
-    osl.shutdown()
+    osl.dispose()
 
 .. note:: 
     Be aware that each time 
@@ -32,4 +33,4 @@ calculator (see example :ref:`ref_simple_calculator`):
     osl = Optislang()
     path_to_file = examples.get_files('simple_calculator')[0]
     osl.run_python_file(file_path=path_to_file)
-    osl.shutdown()
+    osl.dispose()

doc/source/user_guide/troubleshooting.rst

@@ -11,7 +11,7 @@ parameter ``loglevel`` when launching optiSLang:
 
     from ansys.optislang.core import Optislang
     osl = Optislang(loglevel='DEBUG')
-    osl.shutdown()
+    osl.dispose()
 
 Common issues
 -------------
@@ -25,6 +25,6 @@ when launching optiSLang:
 
     from ansys.optislang.core import Optislang
     osl = Optislang(ini_timeout=30)
-    osl.shutdown()
+    osl.dispose()
 
 

examples/01_ten_bar_truss.py

@@ -50,7 +50,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/02_1_oscillator_robustness.py

@@ -44,7 +44,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/02_2_oscillator_python_system.py

@@ -44,7 +44,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/02_3_oscillator_optimization_on_EA.py

@@ -45,7 +45,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/02_4_oscillator_MOP_sensitivity_and_optimization.py

@@ -49,7 +49,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/02_5_oscillator_calibration_systems.py

@@ -48,7 +48,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/03_etk_abaqus.py

@@ -39,7 +39,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/04_python_node_and_help.py

@@ -42,7 +42,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/05_optimizer_settings.py

@@ -40,7 +40,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/06_sensitivity_settings.py

@@ -39,7 +39,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow:

examples/07_simple_calculator.py

@@ -44,7 +44,7 @@
 #########################################################
 # Terminate and cancel project.
 #########################################################
-osl.shutdown()
+osl.dispose()
 
 #########################################################
 # Generated workflow: