Configure the filename for saving the item (#129)

* Configure the filename for saving the item

Author: drnextgis

CHANGELOG.md

@@ -5,19 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- download_item_assets and download_items_assets methods now accept a parameter `file_name` for configuring the filename to save the STAC Item as. If unset, it defaults to `item.json` and if set to `None` the filename is inferred from the ID.
+
 ## [0.5.0] - 2024-05-08
 
-## Deprecated
+### Deprecated
 
 - Support for Python 3.8 has been removed.
 - CLI flags `--skip-upload` and `--skip-validation` deprecated in favor of `--upload/--no-upload` and `--validate/no-validate`
 - Task constructor arguments `skip_upload` and `skip_validation` deprecated in favor of `upload` and `validate`
 
-## Fixed
+### Fixed
 
 - Several CLI arguments were missing `help` descriptions
 
-## Changed
+### Changed
 
 - Replaced the use of fsspec with stac-asset for downloading Item Assets
 - `--local` flag no longer turns off validation
@@ -30,7 +36,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Collection assignment now assigns the first matching collection expression, rather
   than the last.
 
-## Added
+### Added
 
 - Property `collection_mapping` to `Task` class to retrieve the collection mappings
   from upload_options

stactask/asset_io.py

@@ -21,11 +21,12 @@ async def download_item_assets(
     path_template: str = "${collection}/${id}",
     config: Optional[DownloadConfig] = None,
     keep_non_downloaded: bool = True,
+    file_name: Optional[str] = "item.json",
 ) -> Item:
     return await stac_asset.download_item(
         item=item.clone(),
         directory=LayoutTemplate(path_template).substitute(item),
-        file_name="item.json",
+        file_name=file_name,
         config=config,
         keep_non_downloaded=keep_non_downloaded,
     )
@@ -36,6 +37,7 @@ async def download_items_assets(
     path_template: str = "${collection}/${id}",
     config: Optional[DownloadConfig] = None,
     keep_non_downloaded: bool = True,
+    file_name: Optional[str] = "item.json",
 ) -> list[Item]:
     return await asyncio.gather(
         *[
@@ -45,6 +47,7 @@ async def download_items_assets(
                     path_template=path_template,
                     config=config,
                     keep_non_downloaded=keep_non_downloaded,
+                    file_name=file_name,
                 )
             )
             for item in items

stactask/task.py

@@ -243,6 +243,7 @@ def download_item_assets(
         path_template: str = "${collection}/${id}",
         config: Optional[DownloadConfig] = None,
         keep_non_downloaded: bool = True,
+        file_name: Optional[str] = "item.json",
     ) -> Item:
         """Download provided asset keys for the given item. Assets are
         saved in workdir in a directory (as specified by path_template), and
@@ -256,13 +257,15 @@ def download_item_assets(
                 where to store downloaded files.
             keep_original_filenames (Optional[bool]): Controls whether original
                 file names should be used, or asset key + extension.
+            file_name (Optional[str]): The name of the item file to save.
         """
         return asyncio.get_event_loop().run_until_complete(
             download_item_assets(
                 item,
                 path_template=str(self._workdir / path_template),
                 config=config,
                 keep_non_downloaded=keep_non_downloaded,
+                file_name=file_name,
             )
         )
 
@@ -272,6 +275,7 @@ def download_items_assets(
         path_template: str = "${collection}/${id}",
         config: Optional[DownloadConfig] = None,
         keep_non_downloaded: bool = True,
+        file_name: Optional[str] = "item.json",
     ) -> list[Item]:
         """Download provided asset keys for the given items. Assets are
         saved in workdir in a directory (as specified by path_template), and
@@ -286,6 +290,7 @@ def download_items_assets(
                 where to store downloaded files.
             keep_original_filenames (Optional[bool]): Controls whether original
                 file names should be used, or asset key + extension.
+            file_name (Optional[str]): The name of the item file to save.
         """
         return list(
             asyncio.get_event_loop().run_until_complete(
@@ -294,6 +299,7 @@ def download_items_assets(
                     path_template=str(self._workdir / path_template),
                     config=config,
                     keep_non_downloaded=keep_non_downloaded,
+                    file_name=file_name,
                 )
             )
         )