kaitiaki.terminal
=================

.. py:module:: kaitiaki.terminal


Functions
---------

.. autoapisummary::

   kaitiaki.terminal.execute
   kaitiaki.terminal._custom_subprocess_handler


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

.. py:function:: execute(command, timeout=5 * 60, cwd=None, warn=True)

   Executes a terminal command.

   Has a default timeout period of 5 minutes.

   :param command {string} -- The command to execute.:

   :keyword timeout {int} -- The time:
   :kwtype timeout {int} -- The time: in seconds
   :keyword should execute for at most. (default: {5*60})

   :returns: tuple -- A 3-tuple representing (stdout, stderr, reason for termination)


.. py:function:: _custom_subprocess_handler(command, timeout=5 * 60, cwd=None)

   Okay, this one deserves an explanation.

   I noticed that for jobs that took longer than timeout seconds
   to run, they wouldn't be killed correctly. See the following SO
   post that I made:

   https://stackoverflow.com/questions/70587181/terminate-child-process-on-subprocess-timeoutexpired/72135833

   So what I ended up finding out is that Python treats subprocesses
   which spawn groups weirdly. STARS, I suppose, does such
   a thing. Essentially, the SIGKILL signal gets sent to the
   subprocess -- *but not the group*. In turn, this means that
   the subprocesses that do spawn groups don't get killed when
   a TimeoutException is thrown. So, what follows is a copy
   of the Python source code, with the group-killer added
   (see "the magic line!" below).

   © original author. Modified on 06 May 2022 by Sean Richards
   (@Krytic).