Added iris.data.download() function.

iris/_tests/test_data.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 import pytest
+import pathlib
 import urlpath
 import astropy.time
 import iris
@@ -59,3 +60,31 @@ def test_urls_hek(
     assert len(result) > 0
     for url in result:
         assert isinstance(url, urlpath.URL)
+
+
+@pytest.mark.parametrize(
+    argnames="urls",
+    argvalues=[
+        iris.data.urls_hek(
+            obs_id=3882010194,
+            limit=1,
+            spectrograph=False,
+        ),
+    ],
+)
+@pytest.mark.parametrize("directory", [None])
+@pytest.mark.parametrize("overwrite", [False])
+def test_download(
+    urls: list[urlpath.URL],
+    directory: None | pathlib.Path,
+    overwrite: bool,
+):
+    result = iris.data.download(
+        urls=urls,
+        directory=directory,
+        overwrite=overwrite,
+    )
+    assert isinstance(result, list)
+    assert len(urls) == 1
+    for file in result:
+        assert file.exists()

iris/data.py

@@ -3,13 +3,15 @@
 """
 
 from __future__ import annotations
+import pathlib
 import requests
 import urlpath
 import astropy.time
 
 __all__ = [
     "query_hek",
     "urls_hek",
+    "download",
 ]
 
 
@@ -166,3 +168,58 @@ def urls_hek(
                         result.append(urlpath.URL(url))
 
     return result
+
+
+def download(
+    urls: list[urlpath.URL],
+    directory: None | pathlib.Path = None,
+    overwrite: bool = False,
+) -> list[pathlib.Path]:
+    """
+    Download the given URLs to a specified directory.
+    If `overwrite` is :obj:`False`, the file will not be downloaded if it exists.
+
+    Parameters
+    ----------
+    urls
+        The URLs to download.
+    directory
+        The directory to place the downloaded files.
+    overwrite
+        Boolean flag controlling whether to overwrite existing files.
+
+
+    Examples
+    --------
+    Download the most recent "A1: QS monitoring" SJI files
+
+    .. jupyter-execute::
+
+        import iris
+
+        urls = iris.data.urls_hek(
+            description="A1: QS monitoring",
+            limit=1,
+            spectrograph=False,
+        )
+
+        iris.data.download(urls)
+    """
+    if directory is None:
+        directory = pathlib.Path.home() / ".iris/cache"
+
+    directory.mkdir(parents=True, exist_ok=True)
+
+    result = []
+    for url in urls:
+
+        file = directory / url.name
+
+        if overwrite or not file.exists():
+            r = requests.get(url)
+            with open(file, "wb") as f:
+                f.write(r.content)
+
+        result.append(file)
+
+    return result