flint.sclient
=============

.. py:module:: flint.sclient

.. autoapi-nested-parse::

   Utilities related to running commands in a singularity container



Classes
-------

.. autoapisummary::

   flint.sclient.ContainerCommandResults


Functions
---------

.. autoapisummary::

   flint.sclient.pull_container
   flint.sclient.run_singularity_command
   flint.sclient.singularity_wrapper


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

.. py:class:: ContainerCommandResults

   Bases: :py:obj:`NamedTuple`


   Description of the command execution results


   .. py:attribute:: attempts
      :type:  int

      Number of attempts the command took


.. py:function:: pull_container(container_directory: pathlib.Path, uri: str, file_name: str) -> pathlib.Path

   Download a singularity container from an appropriate ``uri``.

   :param container_directory: Where to store the output container
   :type container_directory: Path
   :param uri: The reference to the container to pull, e.g. docker://profile/container:tag
   :type uri: str
   :param file_name: The output name of the container
   :type file_name: str

   :returns: Location of the new container
   :rtype: Path


.. py:function:: run_singularity_command(image: pathlib.Path, command: str, bind_dirs: pathlib.Path | Collection[pathlib.Path] | None = None, stream_callback_func: Callable | None = None, ignore_logging_output: bool = False, max_retries: int = 2) -> None

   Executes a command within the context of a nominated singularity
   container

   :param image: The singularity container image to use
   :type image: Path
   :param command: The command to execute
   :type command: str
   :param bind_dirs: Specifies a Path, or list of Paths, to bind to in the container. Defaults to None.
   :type bind_dirs: Optional[Union[Path,Collection[Path]]], optional
   :param stream_callback_func: Provide a function that is applied to each line of output text when singularity is running and `stream=True`. IF provide it should accept a single (string) parameter. If None, nothing happens. Defaultds to None.
   :type stream_callback_func: Optional[Callable], optional
   :param ignore_logging_output: If `True` output from the executed singularity command is not logged. Defaults to False.
   :type ignore_logging_output: bool, optional
   :param max_retries: If a callback handler is specified which raised an `AttemptRerunException`, this signifies how many attempts should be made. Each rerun will recall `run_singularity_command` lowering this value. Defaults to 2.
   :type max_retries: int, optional

   :raises FileNotFoundError: Thrown when container image not found
   :raises CalledProcessError: Thrown when the command into the container was not successful


.. py:function:: singularity_wrapper(fn: Callable) -> Callable

   A decorator function to around another function that when executed
   returns a command to execute within a container. The returned function has
   the arguments as ``run_singularity_command``, and any unused keywords are
   passed to the wrapped function.

   :param fn: The function that generates the command to execute
   :type fn: Callable

   :returns: Wrapper function
   :rtype: Callable