imaging_api.services.download
=============================

.. py:module:: imaging_api.services.download


Attributes
----------

.. autoapisummary::

   imaging_api.services.download.XNAT_URL
   imaging_api.services.download.BASE_IMAGES_DOWNLOAD_DIR


Functions
---------

.. autoapisummary::

   imaging_api.services.download.download_and_unzip_images
   imaging_api.services.download.format_download_url
   imaging_api.services.download.download_file
   imaging_api.services.download.unzip_file


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

.. py:data:: XNAT_URL
   :value: 'http://xnat-web:8080'


.. py:data:: BASE_IMAGES_DOWNLOAD_DIR

.. py:function:: download_and_unzip_images(central_hub_project_id: str, accession_id: str, net_id: str, assessor_type: str, resource_type: str, headers: dict[str, str]) -> str
   :async:


   Downloads XNAT experiment image data corresponding to a given accession ID and encrypted central hub project id.

   If data exists for the experiment, all image scan resources will be downloaded and the location returned.

   All data is downloaded in a single .zip file. Once the file download is complete, this method will then attempt
   to unzip the folder and delete the existing .zip file.

   :param central_hub_project_id: Central Hub project ID. Corresponds to XNAT secondary ID.
   :type central_hub_project_id: str
   :param accession_id: The unique value for a study stored in PACS. Corresponds to XNAT experiment label.
   :type accession_id: str
   :param net_id: The ID of the FL net that will run the training.
   :type net_id: str
   :param assessor_type: The type of assessor to use for the download ("scan" or "assessor").
   :type assessor_type: str
   :param resource_type: XNAT resource type e.g DICOM/NIFTI. ALL will download all resources. Custom value is
   :type resource_type: str
   :param allowed if researcher has added their own custom XNAT resource type into scans.:
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: The path to the unzipped folder containing the downloaded images.
   :rtype: str

   :raises imaging_api.utils.exceptions.NotFoundError: If the project with the given ID is not found, if no experiments are
   :raises found for the given accession ID, if no data is found at the download URL, or if the ZIP file is not found after:
   :raises download.:
   :raises ValueError: If the net ID attempts path traversal outside the base images directory.
   :raises Exception: If there is an error during any of the requests to XNAT, during the download process, or during the
   :raises unzipping process.:


.. py:function:: format_download_url(project_id: str, subject_id: str, experiment_id_or_label: str, assessor_type: str = 'scan', resource_type: str = 'NIFTI') -> str

   Formats the XNAT API URL to download experiment scan images.

   :param project_id: XNAT project ID.
   :type project_id: str
   :param subject_id: XNAT subject ID.
   :type subject_id: str
   :param experiment_id_or_label: XNAT experiment ID or its label.
   :type experiment_id_or_label: str
   :param assessor_type: Type of assessor (scan or assessor).
   :type assessor_type: str
   :param resource_type: Resource type (e.g. `NIFTI`, `DICOM`, etc.).
   :type resource_type: str

   :returns: Formatted URL for downloading images.
   :rtype: str


.. py:function:: download_file(url: str, destination_path: str, headers: dict[str, str]) -> str

   Downloads a file from the given URL using an XNAT auth headers.

   :param url: URL to download the file from.
   :type url: str
   :param destination_path: Path to save the downloaded file.
   :type destination_path: str
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: Path to the downloaded file.
   :rtype: str

   :raises imaging_api.utils.exceptions.NotFoundError: If XNAT has no data at the given URL (remote 404).
   :raises imaging_api.utils.exceptions.LocalStorageError: If the local filesystem cannot accept the
       downloaded file (missing/unwritable destination directory, disk full, etc.).
   :raises Exception: If there is an upstream/transport error during the download request.


.. py:function:: unzip_file(zip_path: str, extract_dir: str, new_name: str) -> str

   Extracts a ZIP file and renames the directory.

   :param zip_path: Path to the ZIP file.
   :type zip_path: str
   :param extract_dir: Directory to extract the contents.
   :type extract_dir: str
   :param new_name: New name for the extracted directory.
   :type new_name: str

   :returns: Path to the renamed directory.
   :rtype: str

   :raises FileNotFoundError: If the ZIP file does not exist.
   :raises ValueError: If the ZIP file contains path traversal entries (zip slip),
       or if new_name attempts path traversal outside extract_dir.