feat: add stream_href method

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- `open_href` ([#123](https://github.com/stac-utils/stac-asset/pull/123))
+
 ## [0.2.3] - 2023-10-20
 
 ### Added

src/stac_asset/__init__.py

@@ -21,6 +21,7 @@
     download_collection,
     download_item,
     download_item_collection,
+    open_href,
     read_href,
 )
 from .client import Client
@@ -63,5 +64,6 @@
     "download_collection",
     "download_item",
     "download_item_collection",
+    "open_href",
     "read_href",
 ]

src/stac_asset/_functions.py

@@ -9,6 +9,7 @@
 from pathlib import Path
 from types import TracebackType
 from typing import (
+    AsyncIterator,
     List,
     Optional,
     Set,
@@ -456,27 +457,44 @@ async def asset_exists(
         return True
 
 
-async def read_href(
+async def open_href(
     href: str, config: Optional[Config] = None, clients: Optional[List[Client]] = None
-) -> bytes:
-    """Reads an href and returns its bytes.
+) -> AsyncIterator[bytes]:
+    """Opens an href and yields byte chunks.
 
     Args:
         href: The href to read
         config: The download configuration to use
         clients: Any pre-configured clients to use
 
-    Returns:
+    Yields:
         bytes: The bytes from the href
     """
     if config is None:
         config = Config()
     clients_ = Clients(config, clients=clients)
     async with await clients_.get_client(href) as client:
-        data = b""
         async for chunk in client.open_href(href):
-            data += chunk
-        return data
+            yield chunk
+
+
+async def read_href(
+    href: str, config: Optional[Config] = None, clients: Optional[List[Client]] = None
+) -> bytes:
+    """Reads an href and returns its bytes.
+
+    Args:
+        href: The href to read
+        config: The download configuration to use
+        clients: Any pre-configured clients to use
+
+    Returns:
+        bytes: The bytes from the href
+    """
+    data = b""
+    async for chunk in open_href(href, config=config, clients=clients):
+        data += chunk
+    return data
 
 
 def make_asset_hrefs_relative(

tests/test_functions.py

@@ -211,6 +211,13 @@ async def test_assert_asset_exists(item: Item) -> None:
         await stac_asset.assert_asset_exists(Asset(href="not-a-file"))
 
 
+async def test_open_href(data_path: Path) -> None:
+    text = b""
+    async for chunk in stac_asset.open_href(str(data_path / "item.json")):
+        text += chunk
+    Item.from_dict(json.loads(text))
+
+
 async def test_read_href(data_path: Path) -> None:
     text = await stac_asset.read_href(str(data_path / "item.json"))
     Item.from_dict(json.loads(text))