feat: add download_file

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

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",
 ]

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)

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))

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")

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")