flint.archive
=============

.. py:module:: flint.archive

.. autoapi-nested-parse::

   Operations around preserving files and products from an flint run



Functions
---------

.. autoapisummary::

   flint.archive.cli
   flint.archive.copy_files_into
   flint.archive.copy_sbid_files_archive
   flint.archive.create_sbid_tar_archive
   flint.archive.get_archive_options_from_yaml
   flint.archive.get_parser
   flint.archive.resolve_glob_expressions
   flint.archive.tar_files_into
   flint.archive.verify_tarball


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

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

.. py:function:: copy_files_into(copy_out_path: pathlib.Path, files_to_copy: Collection[pathlib.Path]) -> pathlib.Path

   Copy a set of specified files into an output directory, If a file happens to
   be a folder then it will be copied over.

   :param copy_out_path: Path to copy files into
   :type copy_out_path: Path
   :param files_to_copy: Files that shall be copied
   :type files_to_copy: Collection[Path]

   :returns: The path files were copied into
   :rtype: Path


.. py:function:: copy_sbid_files_archive(copy_out_path: pathlib.Path, base_path: pathlib.Path, archive_options: flint.options.ArchiveOptions) -> pathlib.Path

   Copy files from an SBID processing folder into a final location. Uses the
   `copy_file_globs` set of expressions to identify files to copy.

   :param copy_out_path: The output location of the tarball to write
   :type copy_out_path: Path
   :param base_path: The base directory that contains files to archive
   :type base_path: Path
   :param archive_options: Options relating to how files are found and archived
   :type archive_options: ArchiveOptions

   :returns: Output tarball directory
   :rtype: Path


.. py:function:: create_sbid_tar_archive(tar_out_path: pathlib.Path, base_path: pathlib.Path, archive_options: flint.options.ArchiveOptions) -> pathlib.Path

   Create a tar file of key products in a SBID folder.

   :param tar_out_path: The output location of the tarball to write
   :type tar_out_path: Path
   :param base_path: The base directory that contains files to archive
   :type base_path: Path
   :param archive_options: Options relating to how files are found and archived
   :type archive_options: ArchiveOptions

   :returns: Output tarball directory
   :rtype: Path


.. py:function:: get_archive_options_from_yaml(strategy_yaml_path: pathlib.Path) -> dict[str, Any]

   Load the archive options from a specified strategy file

   :param strategy_yaml_path: The path to the strategy yaml file containing archive options
   :type strategy_yaml_path: Path

   :returns: Loaded options for ArchiveOptions
   :rtype: Dict[str, Any]


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

.. py:function:: resolve_glob_expressions(base_path: pathlib.Path, file_re_patterns: Collection[str]) -> tuple[pathlib.Path, Ellipsis]

   Collect a set of files given a base directory and a set of glob expressions. Unique
   paths are returned.

   :param base_path: The base folder with files to consider
   :type base_path: Path
   :param file_re_patterns: An iterable with a set of regular-expression patterns to evaluate
   :type file_re_patterns: Collection[str]

   :returns: Unique collection of paths
   :rtype: Tuple[Path,...]


.. py:function:: tar_files_into(tar_out_path: pathlib.Path, files_to_tar: Collection[pathlib.Path], verify: bool = True) -> pathlib.Path

   Create a tar file given a desired output path and list of files to tar.

   :param tar_out_path: The output path of the tarball. The parent directory will be created if necessary.
   :type tar_out_path: Path
   :param files_to_tar: All the files to tarball up
   :type files_to_tar: Collection[Path]
   :param verify: Verify that the tarball was correctly formed. Defaults to True.
   :type verify: bool, optional

   :raises FileExistsError: The path of the tarball created

   :returns: There exists a tarball of the same name
   :rtype: Path


.. py:function:: verify_tarball(tarball: pathlib.Path) -> bool

   Verify that a tarball was created properly by examining its
   table. Internally this calls ``tar`` through a subprocess call.
   Hence, ``tar`` needs to be available on the system PATH.

   :param tarball: The tarball to examine
   :type tarball: Path

   :returns: True if the ``tar`` exit code is 0, False otherwise
   :rtype: bool