flint.containers
================

.. py:module:: flint.containers

.. autoapi-nested-parse::

   Helper utility functions to download and otherwise manage
   containers required for flint



Attributes
----------

.. autoapisummary::

   flint.containers.KNOWN_CONTAINER_LOOKUP
   flint.containers.LIST_OF_KNOWN_CONTAINERS
   flint.containers.aegean_contaer
   flint.containers.aoflagger_contaer
   flint.containers.askapsoft_contaer
   flint.containers.calibrate_container
   flint.containers.casa_container
   flint.containers.potato_container
   flint.containers.wsclean_container


Classes
-------

.. autoapisummary::

   flint.containers.FlintContainer


Functions
---------

.. autoapisummary::

   flint.containers._pull_and_check_container
   flint.containers._sanity_check_containers
   flint.containers.cli
   flint.containers.download_known_containers
   flint.containers.download_known_containers_coro
   flint.containers.get_known_container_path
   flint.containers.get_parser
   flint.containers.log_known_containers
   flint.containers.verify_known_containers


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

.. py:class:: FlintContainer(/, **data: Any)

   Bases: :py:obj:`flint.options.BaseOptions`


   Item representing a Flint container


   .. py:attribute:: description
      :type:  str | None
      :value: None


      Short description on the purpose of the container


   .. py:attribute:: file_name
      :type:  str

      The expected file name of the container. This will be appended to the container directory path.


   .. py:attribute:: name
      :type:  str

      Name of the container


   .. py:attribute:: tag
      :type:  str
      :value: 'v1.0'


      Tag of the container, if applicable


   .. py:attribute:: uri
      :type:  str

      latest

      :type: URL of the container that can be used to pull with apptainer, e.g. docker

      :type: //alecthomson/aoflagger


.. py:function:: _pull_and_check_container(container_directory: pathlib.Path, known_container: FlintContainer, expected_output_path: pathlib.Path) -> pathlib.Path
   :async:


   Pull a container and check that it was downloaded correctly

   :param container_directory: Output directory to store containers. Will be created if necessary.
   :type container_directory: Path
   :param known_container: Container to download
   :type known_container: FlintContainer
   :param expected_output_path: Expected output path
   :type expected_output_path: Path

   :returns: The expected path of the container
   :rtype: Path


.. py:function:: _sanity_check_containers(container_list: list[FlintContainer] | tuple[FlintContainer, Ellipsis]) -> None

   Do some quick validation checks on the set of loaded containers. Make sure there are no
   duplicated names or file names


.. py:function:: cli() -> None

.. py:function:: download_known_containers(container_directory: pathlib.Path | str, new_tag: str | None = None) -> tuple[pathlib.Path, Ellipsis]

   Download known containers for use throughout flint. This
   calls the async enabled download function and blocks until results
   are gathered.

   :param container_directory: Output directory to store containers. Will be created if necessary.
   :type container_directory: Path | str
   :param new_tag: The tag associated with the containers to download. If None the latest image will be downloaded. Defaults to None.
   :type new_tag: str, optional

   :returns: Paths to all containers downloaded
   :rtype: tuple[Path, ...]


.. py:function:: download_known_containers_coro(container_directory: pathlib.Path | str, new_tag: str | None = None) -> tuple[pathlib.Path, Ellipsis]
   :async:


   Download known containers for use throughout flint.

   :param container_directory: Output directory to store containers. Will be created if necessary.
   :type container_directory: Path | str
   :param new_tag: The tag associated with the containers to download. If None the latest image will be downloaded. Defaults to None.
   :type new_tag: str, optional

   :returns: Paths to all containers downloaded
   :rtype: tuple[Path, ...]


.. py:function:: get_known_container_path(container_directory: pathlib.Path | str, name: str) -> pathlib.Path

   Return the path to a ``flint`` known container. These are containers that
   are downloaded through the ``download_known_containers`` function.

   :param container_directory: Path to directory containing downloaded containers
   :type container_directory: Path | str
   :param name: Name of the container. Note that this is not the file name.
   :type name: str

   :raises ValueError: Raised when the name is not known

   :returns: Path to the requested
   :rtype: Path


.. py:function:: get_parser() -> argparse.ArgumentParser

   Create the CLI argument parser

   :returns: Constructed argument parser
   :rtype: ArgumentParser


.. py:function:: log_known_containers() -> None

   Log the known containers. This simply prints the set of known containers.


.. py:function:: verify_known_containers(container_directory: pathlib.Path | str) -> bool

   Inspect the provided ``container_directory`` to examine that the set of
   containers that are expected to exist are present.

   :param container_directory: Directory to search that should have containers
   :type container_directory: Path | str

   :returns: True is all containers are available. False otherwise.
   :rtype: bool


.. py:data:: KNOWN_CONTAINER_LOOKUP
   :type:  dict[str, FlintContainer]

.. py:data:: LIST_OF_KNOWN_CONTAINERS

.. py:data:: aegean_contaer

.. py:data:: aoflagger_contaer

.. py:data:: askapsoft_contaer

.. py:data:: calibrate_container

.. py:data:: casa_container

.. py:data:: potato_container

.. py:data:: wsclean_container