isofit.data.download
====================

.. py:module:: isofit.data.download

.. autoapi-nested-parse::

   Utility functions for the downloader modules



Functions
---------

.. autoapisummary::

   isofit.data.download.release_metadata
   isofit.data.download.download_file
   isofit.data.download.unzip
   isofit.data.download.untar
   isofit.data.download.prepare_output
   isofit.data.download.cli
   isofit.data.download.preview_paths
   isofit.data.download.isUpToDateGithub
   isofit.data.download.pullFromRepo


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

.. py:function:: release_metadata(org, repo, tag='latest')

   Fetch GitHub metadata for the latest tagged release.

   Credit to Kevin Wurster https://github.com/isofit/isofit/pull/448#issuecomment-1966747551

   :param org: GitHub organization name
   :type org: str
   :param repo: GitHub repository name
   :type repo: str
   :param tag: Release tag to pull
   :type tag: str

   :returns: Metadata returned by the retrieved release
   :rtype: dict


.. py:function:: download_file(url, dstname=None, overwrite=True)

   Stream downloads a file

   :param url: URL to download
   :type url: str
   :param dstname: Destination file name
   :type dstname: str
   :param overwrite: Overwrite the destination file if it already exists
   :type overwrite: bool, default=True

   :returns: **outfile** -- Output downloaded filepath
   :rtype: str


.. py:function:: unzip(file, path=None, rename=None, overwrite=False, cleanup=True)

   Unzips a zipfile

   :param path: Path to extract the zipfile to. Defaults to the directory the zip is found in
   :type path: str, default=None
   :param rename: Renames the extracted data to this
   :type rename: str, default=None
   :param overwrite: Overwrites the path destination with the zip contents if enabled
   :type overwrite: bool, default=False
   :param cleanup: Removes the zip file after completion
   :type cleanup: bool, default=True

   :returns: **dst** -- The extracted output path
   :rtype: str


.. py:function:: untar(file, output)

   Untars a .tar file. Removes the tar file after extracting

   :param file: .tar file to extract
   :type file: str
   :param output: Path to output to
   :type output: str

   :returns: **output** -- The extracted output path
   :rtype: str


.. py:function:: prepare_output(output, default, isdir=False, overwrite=False)

   Prepares the output path by ensuring the parents exist and itself doesn't presently exist.

   :param output: Path to download to
   :type output: str | None
   :param default: Default path defined by the ini file
   :type default: str
   :param isdir: This is supposed to be a directory
   :type isdir: bool, default=False
   :param overwrite: Ignore if the output already exists
   :type overwrite: bool, default=False


.. py:function:: cli()

   Download extra ISOFIT files that do not come with the default installation



.. py:function:: preview_paths()

   Preview download path locations. Paths can be changed from the default by using the overrides on the `isofit` command. See more via `isofit --help`

   
   Example:
   Change the default `data` and `examples` paths
   $ isofit --data /path/to/data --examples /different/path/examples download paths
       Download paths will default to:
       - data = /path/to/data
       - examples = /different/path/examples
   
   These will be saved and may be reviewed:
   $ isofit download paths
       Download paths will default to:
       - data = /path/to/data
       - examples = /different/path/examples


.. py:function:: isUpToDateGithub(owner, repo, name, path=None, debug=print, error=print, **_)

   Checks the installed version against the latest release on Github

   :param owner: Github repository owner
   :type owner: str
   :param repo: Repository name
   :type repo: str
   :param name: Name of the downloader module to retrieve the path from the env ini if path is
                not provided
   :type name: str
   :param path: Path to update. If None, defaults to the ini path
   :type path: str, default=None
   :param debug: Print function to use for debug messages, eg. logging.debug
   :type debug: function, default=print
   :param error: Print function to use for error messages, eg. logging.error
   :type error: function, default=print
   :param \*\*_: Ignores unused params that may be used by other validate functions. This is to
                 maintain compatibility with other functions
   :type \*\*_: dict

   :returns: True if the path is up to date, False otherwise
   :rtype: bool

   .. rubric:: Notes

   The Github workflows watch for the string "[x]" to determine if the cache needs to
   update the data of this module. If your module does not include this string, the
   workflows will never detect updates.


.. py:function:: pullFromRepo(owner, repo, tag, output, version=True, overwrite=False)

   Pulls a release zipfile from a Github repository

   :param owner: Github repository owner
   :type owner: str
   :param repo: Repository name
   :type repo: str
   :param tag: Tag of the release to pull
   :type tag: str
   :param output: Output path to write to
   :type output: pathlib.Path
   :param version: Write the tag's name in a version.txt file
   :type version: bool, default=True
   :param overwrite: Ignore if the output already exists
   :type overwrite: bool, default=False

   :returns: **avail** -- Available path
   :rtype: pathlib.Path