:mod:`sc3nb.process_handling`
=============================

.. py:module:: sc3nb.process_handling

.. autoapi-nested-parse::

   Module for process handling. 

   ..
       !! processed by numpydoc !!


Module Contents
---------------

 

Function List
~~~~~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   sc3nb.process_handling.find_executable
   sc3nb.process_handling.kill_processes




Class List
~~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   sc3nb.process_handling.Process



Content
~~~~~~~

.. py:data:: _LOGGER

.. py:data:: ANSI_ESCAPE

.. py:data:: ALLOWED_PARENTS
   :value: ('scide', 'python', 'tox')


.. py:function:: find_executable(executable: str, search_path: str = None, add_to_path: bool = False)

   
   Looks for executable in os $PATH or specified path


   :Parameters:

       **executable** : str
           Executable to be found

       **search_path** : str, optional
           Path at which to look for, by default None

       **add_to_path** : bool, optional
           Wether to add the provided path to os $PATH or not, by default False



   :Returns:

       str
           Full path to executable




   :Raises:

       FileNotFoundError
           Raised if executable cannot be found







   ..
       !! processed by numpydoc !!

.. py:function:: kill_processes(exec_path, allowed_parents: Optional[tuple] = None)

   
   Kill processes with the same path for the executable.

   If allowed_parent is provided it will be searched in the names of the
   parent processes of the process with the executable path before terminating.
   If it is found the process won't be killed.

   :Parameters:

       **exec_path** : str
           path of the executable to kill

       **allowed_parent** : str, optional
           parents name of processes to keep, by default None














   ..
       !! processed by numpydoc !!

.. exception:: ProcessTimeout(executable, output, timeout, expected)


   **Bases:** :class:`Exception`

   Process Timeout Exception


   Initialize self.  See help(type(self)) for accurate signature.
















   ..
       !! processed by numpydoc !!



   .. py:attribute:: output

   .. py:attribute:: timeout






.. class:: Process(executable: str, programm_args: Optional[Sequence[str]] = None, executable_path: str = None, console_logging: bool = True, kill_others: bool = True, allowed_parents: Sequence[str] = None)


   
   Class for starting a executable and communication with it.


   :Parameters:

       **executable** : str
           Name of executable to start

       **programm_args** : Optional[Sequence[str]], optional
           Arguments to program start with Popen, by default None

       **executable_path** : str, optional
           Path with executalbe, by default system PATH

       **console_logging** : bool, optional
           Flag for controlling console logging, by default True

       **kill_others** : bool, optional
           Flag for controlling killing of other executables with the same name.
           This is useful when processes where left over, by default True

       **allowed_parents** : Sequence[str], optional
           Sequence of parent names that won't be killed
           when kill_others is True, by default None














   ..
       !! processed by numpydoc !!


   .. py:attribute:: executable

   .. py:attribute:: exec_path

   .. py:attribute:: console_logging

   .. py:attribute:: popen_args

   .. py:attribute:: popen

   .. py:attribute:: output_queue

   .. py:attribute:: output_reader_thread



   **Overview:**

   .. autoapisummary::
      :nosignatures:

         sc3nb.process_handling.Process._read_loop
         sc3nb.process_handling.Process.read
         sc3nb.process_handling.Process.empty
         sc3nb.process_handling.Process.write
         sc3nb.process_handling.Process.kill
         sc3nb.process_handling.Process.__del__
         sc3nb.process_handling.Process.__repr__

   .. py:method:: _read_loop()

   .. py:method:: read(expect: Optional[str] = None, timeout: float = 3) -> str

      
      Reads current output from output queue until expect is found


      :Parameters:

          **expect** : str, optional
              str that we expect to find, by default None

          **timeout** : float, optional
              timeout in seconds for waiting for output, by default 3



      :Returns:

          str
              Output of process.




      :Raises:

          ProcessTimeout
              If neither output nor expect is found







      ..
          !! processed by numpydoc !!

   .. py:method:: empty() -> None

      
      Empties output queue.
















      ..
          !! processed by numpydoc !!

   .. py:method:: write(input_str: str) -> None

      
      Send input to process


      :Parameters:

          **input_str** : str
              Input to be send to process







      :Raises:

          RuntimeError
              If writing to process fails







      ..
          !! processed by numpydoc !!

   .. py:method:: kill() -> int

      
      Kill the process.





      :Returns:

          int
              return code of process











      ..
          !! processed by numpydoc !!

   .. py:method:: __del__()

   .. py:method:: __repr__() -> str