Merge pull request #10 from ASFHyP3/develop

Release v0.1.1

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1]
+### Added
+* `fetch_for_scene` docstring to the usage section of the README.
+
 ## [0.1.0]
 ### Added
 * `fetch_for_scene` function to download the best available orbit information for a scene.

README.md

@@ -1,4 +1,4 @@
-# sentinel1-orbits-py
+# s1-orbits
 
 A Python utility for downloading Sentinel-1 Orbit files from the Registry of Open Data on AWS.
 
@@ -30,16 +30,27 @@ python -m pip install s1_orbits
 
 ## Usage
 
+**s1-orbits** provides one function - `fetch_for_scene` - to download the "best available" orbit file for a given scene. This means it will download the *AUX_POEORB* file if it exists; otherwise, it will download the *AUX_RESORB* file. For a more full-featured API, see [sentineleof](https://github.com/scottstanie/sentineleof) or [CDSE's APIs](https://documentation.dataspace.copernicus.eu/APIs.html).
+
 ```python
->>> import s1_orbits
->>> orbit_file = s1_orbits.fetch_for_scene(
-...     scene='S1A_IW_SLC__1SDV_20230727T075102_20230727T075131_049606_05F70A_AE0A',
-...     dir='/data',
-... )
->>> orbit_file
-PosixPath('/data/S1A_OPER_AUX_POEORB_OPOD_20230816T080815_V20230726T225942_20230728T005942.EOF')
+fetch_for_scene(scene: str, dir: Union[pathlib.Path, str] = '.') -> pathlib.Path
+    """
+    For the given scene, downloads the AUX_POEORB file if available, otherwise downloads the AUX_RESORB file.
+
+    Args:
+        scene: The scene name for which to download the orbit file.
+        dir: The directory that the orbit file should download into.
+
+    Raises:
+        InvalidSceneError: Thrown if the scene name is not a proper Sentinel-1 scene name.
+        OrbitNotFoundError: Thrown if an orbit cannot be found for the provided scene.
+
+    Returns:
+        download_path: The path to the downloaded file.
+    """
 ```
 
+
 ## Development
 
 1. Install [git](https://git-scm.com/) and [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html).

src/s1_orbits/s1_orbits.py

@@ -19,6 +19,10 @@ def fetch_for_scene(
         scene: The scene name for which to download the orbit file.
         dir: The directory that the orbit file should download into.
 
+    Raises:
+        InvalidSceneError: Thrown if the scene name is not a proper Sentinel-1 scene name.
+        OrbitNotFoundError: Thrown if an orbit cannot be found for the provided scene.
+
     Returns:
         download_path: The path to the downloaded file.
     """