Add blocking interface

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - `ErrorStrategy` ([#69](https://github.com/stac-utils/stac-asset/pull/69))
 - `fail_fast` ([#69](https://github.com/stac-utils/stac-asset/pull/69))
 - `assert_asset_exists`, `asset_exists`, `Client.assert_href_exists`, `Client.href_exists` ([#81](https://github.com/stac-utils/stac-asset/pull/81), [#85](https://github.com/stac-utils/stac-asset/pull/85))
+- Blocking interface ([#86](https://github.com/stac-utils/stac-asset/pull/86))
 
 ### Changed
 

README.md

@@ -35,7 +35,16 @@ import stac_asset
 
 href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
 item = pystac.from_file(href)
-await stac_asset.download_item(item, ".")
+item = await stac_asset.download_item(item, ".")
+```
+
+If you're working in a fully synchronous application, you can use our blocking interface:
+
+```python
+import stac_asset.blocking
+href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
+item = pystac.from_file(href)
+item = stac_asset.blocking.download_item(item, ".")
 ```
 
 ### CLI

docs/api.rst

@@ -4,6 +4,12 @@ API documentation
 .. automodule:: stac_asset
     :members:
 
+stac_asset.blocking
+-------------------
+
+.. automodule:: stac_asset.blocking
+    :members:
+
 stac_asset.validate
 -------------------
 

pyproject.toml

@@ -31,6 +31,7 @@ dev = [
     "black~=23.3",
     "mypy~=1.3",
     "pre-commit~=3.3",
+    "pystac[validation]>=1.7.3",
     "pytest~=7.3",
     "pytest-asyncio~=0.21",
     "pytest-cov~=4.1",

src/stac_asset/__init__.py

@@ -34,6 +34,7 @@
 )
 from .filesystem_client import FilesystemClient
 from .http_client import HttpClient
+from .messages import Message
 from .planetary_computer_client import PlanetaryComputerClient
 from .s3_client import S3Client
 from .strategy import ErrorStrategy, FileNameStrategy
@@ -52,6 +53,7 @@
     "FileNameStrategy",
     "FilesystemClient",
     "HttpClient",
+    "Message",
     "PlanetaryComputerClient",
     "S3Client",
     "assert_asset_exists",

src/stac_asset/_cli.py

@@ -25,16 +25,15 @@
     StartAssetDownload,
     WriteChunk,
 )
+from .types import MessageQueue
 
 logger = logging.getLogger(__name__)
 click_logging.basic_config(logger)
 
 # Needed until we drop Python 3.8
 if TYPE_CHECKING:
-    AnyQueue = Queue[Any]
     Tqdm = tqdm.tqdm[Any]
 else:
-    AnyQueue = Queue
     Tqdm = tqdm.tqdm
 
 
@@ -210,9 +209,9 @@ async def download_async(
         directory_str = str(directory)
 
     if quiet:
-        queue = None
+        messages = None
     else:
-        queue = Queue()
+        messages = Queue()
 
     type_ = input_dict.get("type")
     if type_ is None:
@@ -232,7 +231,7 @@ async def download() -> Union[Item, ItemCollection]:
                 file_name=file_name,
                 infer_file_name=False,
                 config=config,
-                queue=queue,
+                messages=messages,
             )
 
     elif type_ == "FeatureCollection":
@@ -244,22 +243,22 @@ async def download() -> Union[Item, ItemCollection]:
                 directory_str,
                 file_name=file_name,
                 config=config,
-                queue=queue,
+                messages=messages,
             )
 
     else:
         if not quiet:
             print(f"ERROR: unsupported 'type' field: {type_}", file=sys.stderr)
         sys.exit(2)
 
-    task = asyncio.create_task(report_progress(queue))
+    task = asyncio.create_task(report_progress(messages))
     try:
         output = await download()
     except DownloadError:
         sys.exit(1)
 
-    if queue:
-        await queue.put(None)
+    if messages:
+        await messages.put(None)
     await task
 
     if not quiet:
@@ -278,8 +277,8 @@ async def read_file(href: str, config: Config) -> bytes:
         return data
 
 
-async def report_progress(queue: Optional[AnyQueue]) -> None:
-    if queue is None:
+async def report_progress(messages: Optional[MessageQueue]) -> None:
+    if messages is None:
         return
     progress_bar = tqdm.tqdm(
         unit="B",
@@ -296,7 +295,7 @@ async def report_progress(queue: Optional[AnyQueue]) -> None:
     n = 0
     progress_bar.set_postfix_str(f"{errors} errors")
     while True:
-        message = await queue.get()
+        message = await messages.get()
         if isinstance(message, StartAssetDownload):
             assets += 1
             if message.owner_id:

src/stac_asset/_functions.py

@@ -9,8 +9,6 @@
 from pathlib import Path
 from types import TracebackType
 from typing import (
-    TYPE_CHECKING,
-    Any,
     List,
     Optional,
     Set,
@@ -33,13 +31,7 @@
     StartAssetDownload,
 )
 from .strategy import ErrorStrategy, FileNameStrategy
-from .types import PathLikeObject
-
-# Needed until we drop Python 3.8
-if TYPE_CHECKING:
-    AnyQueue = Queue[Any]
-else:
-    AnyQueue = Queue
+from .types import MessageQueue, PathLikeObject
 
 
 @dataclass
@@ -53,7 +45,7 @@ class Download:
 
     async def download(
         self,
-        messages: Optional[AnyQueue],
+        messages: Optional[MessageQueue],
     ) -> Union[Download, WrappedError]:
         if not os.path.exists(self.path) or self.config.overwrite:
             try:
@@ -134,7 +126,7 @@ async def add(
             )
         stac_object.assets = assets
 
-    async def download(self, messages: Optional[AnyQueue]) -> None:
+    async def download(self, messages: Optional[MessageQueue]) -> None:
         tasks: Set[Task[Union[Download, WrappedError]]] = set()
         for download in self.downloads:
             task = asyncio.create_task(
@@ -199,7 +191,7 @@ async def download_item(
     file_name: Optional[str] = None,
     infer_file_name: bool = True,
     config: Optional[Config] = None,
-    queue: Optional[AnyQueue] = None,
+    messages: Optional[MessageQueue] = None,
     clients: Optional[List[Client]] = None,
 ) -> Item:
     """Downloads an item to the local filesystem.
@@ -212,7 +204,7 @@ async def download_item(
         infer_file_name: If ``file_name`` is None, infer the file name from the
             item's id. This argument is unused if ``file_name`` is not None.
         config: The download configuration
-        queue: An optional queue to use for progress reporting
+        messages: An optional queue to use for progress reporting
         clients: Pre-configured clients to use for access
 
     Returns:
@@ -226,7 +218,7 @@ async def download_item(
 
     async with Downloads(config=config or Config(), clients=clients) as downloads:
         await downloads.add(item, Path(directory), file_name)
-        await downloads.download(queue)
+        await downloads.download(messages)
 
     self_href = item.get_self_href()
     if self_href:
@@ -243,7 +235,7 @@ async def download_collection(
     directory: PathLikeObject,
     file_name: Optional[str] = "collection.json",
     config: Optional[Config] = None,
-    queue: Optional[AnyQueue] = None,
+    messages: Optional[MessageQueue] = None,
     clients: Optional[List[Client]] = None,
 ) -> Collection:
     """Downloads a collection to the local filesystem.
@@ -257,7 +249,7 @@ async def download_collection(
         file_name: The name of the collection file to save. If not provided,
             will not be saved.
         config: The download configuration
-        queue: An optional queue to use for progress reporting
+        messages: An optional queue to use for progress reporting
         clients: Pre-configured clients to use for access
 
     Returns:
@@ -268,7 +260,7 @@ async def download_collection(
     """
     async with Downloads(config=config or Config(), clients=clients) as downloads:
         await downloads.add(collection, Path(directory), file_name)
-        await downloads.download(queue)
+        await downloads.download(messages)
 
     self_href = collection.get_self_href()
     if self_href:
@@ -285,7 +277,7 @@ async def download_item_collection(
     directory: PathLikeObject,
     file_name: Optional[str] = "item-collection.json",
     config: Optional[Config] = None,
-    queue: Optional[AnyQueue] = None,
+    messages: Optional[MessageQueue] = None,
     clients: Optional[List[Client]] = None,
 ) -> ItemCollection:
     """Downloads an item collection to the local filesystem.
@@ -296,7 +288,7 @@ async def download_item_collection(
         file_name: The name of the item collection file to save. If not
             provided, will not be saved.
         config: The download configuration
-        queue: An optional queue to use for progress reporting
+        messages: An optional queue to use for progress reporting
         clients: Pre-configured clients to use for access
 
     Returns:
@@ -310,7 +302,7 @@ async def download_item_collection(
             item.set_self_href(None)
             root = Path(directory) / item.id
             await downloads.add(item, root, None)
-        await downloads.download(queue)
+        await downloads.download(messages)
     if file_name:
         dest_href = Path(directory) / file_name
         for item in item_collection.items:
@@ -387,6 +379,7 @@ async def download_asset(
             )
         raise error
 
+    asset.href = str(path)
     if messages:
         await messages.put(FinishAssetDownload(key=key, href=href, path=path))
     return asset