From 9534b40eb2c86ff5e511afab851cf012d05473c7 Mon Sep 17 00:00:00 2001
From: Pete Gadomski <pete.gadomski@gmail.com>
Date: Fri, 24 May 2024 09:15:20 -0600
Subject: [PATCH] feat: add download_file

---
 CHANGELOG.md                 |  4 ++++
 src/stac_asset/__init__.py   |  2 ++
 src/stac_asset/_functions.py | 21 +++++++++++++++++++++
 src/stac_asset/blocking.py   | 17 +++++++++++++++++
 tests/test_blocking.py       |  7 +++++++
 tests/test_functions.py      |  5 +++++
 6 files changed, 56 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c730a2c..e11684c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- `download_file` ([#122](https://github.com/stac-utils/stac-asset/pull/172))
+
 ## [0.3.2] - 2024-05-20
 
 ### Added
diff --git a/src/stac_asset/__init__.py b/src/stac_asset/__init__.py
index 87606d1..453e1d0 100644
--- a/src/stac_asset/__init__.py
+++ b/src/stac_asset/__init__.py
@@ -18,6 +18,7 @@
     asset_exists,
     download_asset,
     download_collection,
+    download_file,
     download_item,
     download_item_collection,
     open_href,
@@ -63,6 +64,7 @@
     "download_collection",
     "download_item",
     "download_item_collection",
+    "download_file",
     "open_href",
     "read_href",
 ]
diff --git a/src/stac_asset/_functions.py b/src/stac_asset/_functions.py
index 3f920d4..2593f41 100644
--- a/src/stac_asset/_functions.py
+++ b/src/stac_asset/_functions.py
@@ -584,3 +584,24 @@ def get_absolute_asset_href(asset: Asset, alternate_assets: List[str]) -> Option
                         f"{alternate}"
                     )
     return asset.get_absolute_href()
+
+
+async def download_file(
+    href: str,
+    destination: PathLikeObject,
+    config: Optional[Config] = None,
+    clients: Optional[List[Client]] = None,
+) -> None:
+    """Downloads a file collection to the local filesystem.
+
+    Args:
+        href: The source href
+        destination: The destination file path
+        config: The download configuration
+        clients: Pre-configured clients to use for access
+    """
+    if config is None:
+        config = Config()
+    clients_ = Clients(config, clients=clients)
+    client = await clients_.get_client(href)
+    await client.download_href(href, destination)
diff --git a/src/stac_asset/blocking.py b/src/stac_asset/blocking.py
index 7584af7..603705d 100644
--- a/src/stac_asset/blocking.py
+++ b/src/stac_asset/blocking.py
@@ -235,3 +235,20 @@ def read_href(
         bytes: The bytes from the href
     """
     return asyncio.run(_functions.read_href(href, config, clients))
+
+
+def download_file(
+    href: str,
+    destination: PathLikeObject,
+    config: Optional[Config] = None,
+    clients: Optional[List[Client]] = None,
+) -> None:
+    """Downloads a file collection to the local filesystem.
+
+    Args:
+        href: The source href
+        destination: The destination file path
+        config: The download configuration
+        clients: Pre-configured clients to use for access
+    """
+    return asyncio.run(_functions.download_file(href, destination, config, clients))
diff --git a/tests/test_blocking.py b/tests/test_blocking.py
index 58fc88b..c896063 100644
--- a/tests/test_blocking.py
+++ b/tests/test_blocking.py
@@ -44,3 +44,10 @@ def test_asset_exists(item: Item) -> None:
 def test_read_href(data_path: Path) -> None:
     text = stac_asset.blocking.read_href(str(data_path / "item.json"))
     Item.from_dict(json.loads(text))
+
+
+def test_download_file(data_path: Path, tmp_path: Path) -> None:
+    stac_asset.blocking.download_file(
+        str(data_path / "item.json"), tmp_path / "item.json"
+    )
+    Item.from_file(tmp_path / "item.json")
diff --git a/tests/test_functions.py b/tests/test_functions.py
index 91d9852..52ee5e1 100644
--- a/tests/test_functions.py
+++ b/tests/test_functions.py
@@ -241,3 +241,8 @@ async def test_keep_non_downloaded(item: Item, tmp_path: Path) -> None:
         item, tmp_path, config=Config(include=["data"]), keep_non_downloaded=True
     )
     assert len(item.assets) == 2
+
+
+async def test_download_file(data_path: Path, tmp_path: Path) -> None:
+    await stac_asset.download_file(str(data_path / "item.json"), tmp_path / "item.json")
+    Item.from_file(tmp_path / "item.json")