_casp_process.py

"""! This module defines classes that provide interfaces to perform low level read/write operations with CASP executables. Each class defined in this module creates a subprocess for a particular executable and provides interfaces to talk to that subprocess based on funtionality and need.
In most cases interfaces defined in this module are not required to be used directly by the user. It is recommended to use the wrapper functions provided in \ref casp.py and \ref casp_gpio.py modules instead.
Typical interfaces that this module provides:
    - Interface to create an executable as a subprocess
    - Interface to write data to the subprocess and read the returned response from the subprocess
    - Interface to terminate the subprocess
 
This module also provides global objects for all classes defined in this module. These global objects are used directly by upper level interfaces to provide required functionalities.
"""

import subprocess
import sys
import os
import time
import casp_paths
 
if sys.version_info[:3] < (3,9):
    from typing import List as list

class CaspProcess:
    """! CaspProcess class provides interfaces to create, read/write and terminate 'CASP' executable as a subprocess.
    A global object of this class \ref casp_proc is also created in this module. It is used by upper level interfaces from \ref casp.py module.
    """
 
    def init(self, make_visible: bool=False, casp_file: str="CASP-Eval"):
        """! Starts a python subprocess for 'CASP or CASP-Eval' executable with command line interface (CLI) enabled.
 
        Arguments:
 
            make_visible: allows the GUI window to be visible or hidden. Default is to hide the window.
 
            casp_file: allows user to specify different version of CASP executable other than the evaluation version. In most cases this argument is not required to be specified by the user.
        """
        casp_fpath = os.path.join(casp_paths.casp_exe_path, casp_file)
        #form arguments
        arguments: list[str]
        if make_visible == True:
            arguments = ["#cli"]
        else:
            arguments = ["#cli", "#hide"]
        #form command
        command = [casp_fpath] + arguments
        #start process
        self.__process = subprocess.Popen(
            command,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,  # Handle as strings instead of bytes
            bufsize=0   # Unbuffered
        )
        #wait till casp initializes
        print(f"Initializing CASP...")
        response = self.__process.stdout.readline()
        print(f"CASP: {response.strip()}")
 
    def write(self, cmd: str, arguments: list[str]=None) -> str:
        """! In general, data exchange betweem the python side interfaces and the executable is in the form of 'command' and a list of corresponding 'arguments'.
        This interface writes the command along with its argument list to the subprocess. Waits for the response and returns the response received from the subprocess.
 
        Arguments:
 
            cmd: command string to write to the subprocess
 
            arguments: argument list to write to the subprocess
 
        Return Value:
 
            Response string received from the subprocess
        """
        arg_len = 0
        if arguments:
            arg_len = len(arguments)
        arg = cmd
        if arg_len > 1:
            arg = arg + '$' + '$'.join(arguments)
        elif arg_len > 0:
            arg = arg + '$' + arguments[0]
        self.__process.stdin.write(arg + '\n') #'\n' is must at the end
        self.__process.stdin.flush()
        response = self.__process.stdout.readline() #response should also end with '\n'
        #print(response.strip())
        return response.strip()
 
    def close(self):
        """! Closes or terminates the subprocess and waits till subprocess is terminated before returning."""
        print(f"Terminating CASP process...")
        self.__process.stdin.close()
        time.sleep(2); #give some time for the msgs to log.
        self.__process.terminate()
        self.__process.wait()
        print(f"...Done")

class CaspBlockEditorProcess:
    """! CaspBlockEditorProcess class provides interfaces to create, read/write and terminate 'BlockEditor' executable as a subprocess.
    A global object of this class \ref casp_be_proc is also created in this module. It is used by upper level interfaces from \ref casp_be.py module.
    """
 
    def init(self, casp_file: str="BlockEditor"):
        """! Starts a python subprocess for 'BlockEditor' executable with command line interface (CLI) enabled.
 
        Arguments:
 
            casp_file: allows user to specify different version of 'BlockEditor' executable when required. In most cases this argument is not required to be specified by the user.
        """
        casp_fpath = os.path.join(casp_paths.casp_exe_path, casp_file)
        command = [casp_fpath, "#cli_on"]
        #start process
        self.__process = subprocess.Popen(
            command,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,  # Handle as strings instead of bytes
            bufsize=0   # Unbuffered
        )
        #wait till casp initializes
        print(f"Initializing CASP Block Editor...")
        response = self.__process.stdout.readline()
        print(f"CASP: {response.strip()}")
 
    def write(self, cmd: str, arguments: list[str]=None) -> str:
        """! In general, data exchange betweem the python side interfaces and the executable is in the form of 'command' and a list of corresponding 'arguments'.
        This interface writes the command along with its argument list to the subprocess. Waits for the response and returns the response received from the subprocess.
 
        Arguments:
 
            cmd: command string to write to the subprocess
 
            arguments: argument list to write to the subprocess
 
        Return Value:
 
            Response string received from the subprocess
        """
        arg_len = 0
        if arguments:
            arg_len = len(arguments)
        arg = cmd
        if arg_len > 1:
            arg = arg + '$' + '$'.join(arguments)
        elif arg_len > 0:
            arg = arg + '$' + arguments[0]
        self.__process.stdin.write(arg + '\n') #'\n' is must at the end
        self.__process.stdin.flush()
        response = self.__process.stdout.readline() #response should also end with '\n'
        #print(response.strip())
        return response.strip()
 
    def close(self):
        """! Closes or terminates the subprocess and waits till subprocess is terminated before returning."""
        print(f"Terminating CASP Block Editor process...")
        self.__process.stdin.close()
        time.sleep(2); #give some time for the msgs to log.
        self.__process.terminate()
        self.__process.wait()
        print(f"...Done")

class CaspBlockViewerProcess:
    """! CaspBlockViewerProcess class provides interfaces to start and terminate 'BlockViewer' executable as a subprocess. The 'BlockViewer' executable is used to browse CASP blocks.
    A global object of this class \ref casp_bv_proc is also created in this module. It is used by upper level interfaces from \ref casp.py module to invoke the block viewer executable.
    """
 
    def init(self, casp_file: str="BlockViewer"):
        """! Starts a subprocess for 'BlockViewer' executable with command line interface (CLI) enabled.
 
        Arguments:
 
            casp_file: allows user to specify different version of 'BlockViewer' executable when required. In most cases this argument is not required to be specified by the user.
        """
        casp_fpath = os.path.join(casp_paths.casp_exe_path, casp_file)
        #start process
        self.__process = subprocess.Popen(
            casp_fpath,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,  # Handle as strings instead of bytes
            bufsize=0   # Unbuffered
        )
 
    def close(self):
        """! Closes or terminates the subprocess and waits till subprocess is terminated before returning."""
        self.__process.stdin.close()
        self.__process.terminate()
        self.__process.wait()

class CaspGpioProcess:
    """! CaspGpioProcess class provides interfaces to create, read/write and terminate 'casp_gpio_bridge' executable as a subprocess.
    A global object of this class \ref casp_gpio_proc is also created in this module. It is used by upper level interfaces from \ref casp_gpio.py module.
    """
 
    def init(self, casp_file: str="casp_gpio_bridge"):
        """! Starts a subprocess for 'casp_gpio_bridge' executable with command line interface (CLI) enabled.
        Arguments:
 
            casp_file: allows user to specify different version of the executable when required. In most cases this argument is not required to be specified by the user.
        """
        casp_fpath = os.path.join(casp_paths.casp_exe_path, casp_file)
        command = [casp_fpath, "#cli"]
        #start process
        self.__process = subprocess.Popen(
            command,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,  # Handle as strings instead of bytes
            bufsize=0   # Unbuffered
        )
        #wait till casp initializes
        print(f"Initializing...")
        response = self.__process.stdout.readline()
        print(f"CASP: {response.strip()}")
 
    def write(self, cmd: str, arguments: list[str]=None) -> str:
        """! Data exchange betweem the python side interfaces and the executable is in the form of 'command' and a list of corresponding 'arguments'.
        This interface writes the command along with its argument list to the subprocess.
        Waits for the response and returns the response received from the subprocess.
 
        Arguments:
 
            cmd: command string to write to the subprocess
 
            arguments: argument list to write to the subprocess
 
        Return Value:
 
            Response string received from the subprocess
        """
        arg_len = 0
        if arguments:
            arg_len = len(arguments)
        arg = cmd
        if arg_len > 1:
            arg = arg + '$' + '$'.join(arguments)
        elif arg_len > 0:
            arg = arg + '$' + arguments[0]
        self.__process.stdin.write(arg + '\n') #'\n' is must at the end
        self.__process.stdin.flush()
        response = self.__process.stdout.readline() #response should also end with '\n'
        #print(response.strip())
        return response.strip()
 
    def close(self):
        """! Closes or terminates the subprocess and waits till subprocess is terminated before returning."""
        print(f"Terminating process...")
        self.__process.stdin.close()
        time.sleep(2); #give some time for the msgs to log.
        self.__process.terminate()
        self.__process.wait()
        print(f"...Done")


casp_proc = CaspProcess()
 

casp_be_proc = CaspBlockEditorProcess()
 

casp_bv_proc = CaspBlockViewerProcess()
 

casp_gpio_proc = CaspGpioProcess()