Merge pull request #183 from nsidc/cryo-95

Update documentation and publishing workflow

.github/workflows/publish.yml

@@ -1,10 +1,7 @@
 name: Publish
 on:
-  push:
-    branch:
-      - main
-    tags:
-      - "v*.*.*"
+  release:
+    types: [published]
 
 jobs:
   build:

CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## [UNRELEASED]
 
-* name change
+## [v0.4.6] 2022-12-13
+
+* Features:
+    * search collections by DOI
+    * new API documentation and simplified notation to access data
+* CI changes:
+    * only run the publish workflow after a release on github
 
 ## [v0.4.1] 2022-11-02
 

README.md

@@ -9,15 +9,15 @@
 </a>
 
 <a href="https://pypi.org/project/earthdata" target="_blank">
-    <img src="https://img.shields.io/pypi/v/earthdata?color=%2334D058&label=pypi%20package" alt="Package version">
+    <img src="https://img.shields.io/pypi/v/earthaccess?color=%2334D058&label=pypi%20package" alt="Package version">
 </a>
 
 <a href="https://pypi.org/project/earthdata/" target="_blank">
-    <img src="https://img.shields.io/pypi/pyversions/earthdata.svg" alt="Python Versions">
+    <img src="https://img.shields.io/pypi/pyversions/earthaccess.svg" alt="Python Versions">
 </a>
 
 <a href="https://nsidc.github.io/earthdata/" target="_blank">
-    <img src="https://readthedocs.org/projects/earthdata/badge/?version=latest&style=plastic" alt="Documentation link">
+    <img src="https://readthedocs.org/projects/earthaccess/badge/?version=latest&style=plastic" alt="Documentation link">
 </a>
 
 </p>

docs/tutorials/authenticate.md

@@ -0,0 +1,24 @@
+## Authenticate with Earthdata Login
+
+Import earthaccess
+```py
+from earthaccess
+```
+
+If you have a .netrc file with your Earthdata Login credentials
+
+```py
+auth = earthaccess.login(strategy="netrc")
+```
+
+If your Earthdata Login credentials are set as environment variables: EDL_USERNAME, EDL_PASSWORD
+
+```py
+auth = earthaccess.login(strategy="environment")
+```
+
+If you wish to enter your Earthdata Login credentials when prompted 
+
+```py
+auth = earthaccess.login(strategy="interactive", persist=True)
+```

docs/tutorials/cloud.md

@@ -1 +1,3 @@
-# Search and access of cloud-based datasets
+# Direct S3 access for cloud-based datasets
+
+Coming soon 

docs/tutorials/demo.ipynb

@@ -11,7 +11,7 @@
     "## Overview\n",
     "\n",
     "\n",
-    "# <img src=\"https://logos-world.net/wp-content/uploads/2020/05/NASA-Logo-1959-present.png\" width=\"100px\" align=\"middle\" /> NASA Earthdata API Client 🌍\n",
+    "# <img src=\"https://logos-world.net/wp-content/uploads/2020/05/NASA-Logo-1959-present.png\" width=\"100px\" align=\"middle\" /> Introducing NASA earthaccess 🌍\n",
     "\n",
     "\n",
     "\n",
@@ -606,7 +606,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,

docs/tutorials/onprem.md

@@ -1 +1,3 @@
-# Data access for on-prem datasets
+# Download data for on-prem datasets 
+
+Coming soon

docs/tutorials/restricted-datasets.ipynb

@@ -7,7 +7,7 @@
     "tags": []
    },
    "source": [
-    "# Datasets under an access control list (ACL)\n",
+    "# Accessing Datasets under an Access Control List (ACL)\n",
     "\n",
     "## <img src=\"https://logos-world.net/wp-content/uploads/2020/05/NASA-Logo-1959-present.png\" width=\"100px\" align=\"middle\" /> NASA Earthdata API Client 🌍\n",
     "\n",
@@ -309,7 +309,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,

docs/tutorials/search-collections.md

@@ -0,0 +1,3 @@
+# how to search for data collections using spatial, temporal,  keyword filters 
+
+Coming soon

docs/tutorials/search-granules.md

@@ -0,0 +1,15 @@
+Import earthaccess library and search for granules within a data set using spatial and temporal filters. You need to know the short name of the data set which can be found on the data set landing page.
+
+```py
+import earthaccess
+
+results = earthaccess.search_data(
+    short_name = "ATL06",
+    version = "005"'
+    cloud_hosted = True, 
+    bounding_box = (-10,20,10,50),
+    temporal = ("2020-02", "2020-03"),
+    count = 100
+)
+```
+

docs/tutorials/storage-location.md

@@ -0,0 +1,3 @@
+# Determine if a data set is on-prem or in the cloud 
+
+Coming soon

earthaccess/api.py

@@ -135,11 +135,8 @@ def download(
 ) -> List[str]:
     """Retrieves data granules from a remote storage system.
 
-       * If we run this in the cloud we are moving data from S3 to a cloud compute instance (EC2, AWS Lambda)
-       * If we run it outside the us-west-2 region and the data granules are part of a cloud-based
-         collection the method will not get any files.
-       * If we requests data granules from an on-prem collection the data will be effectively downloaded
-         to a local directory.
+       * If we run this in the cloud, we will be using S3 to move data to `local_path`
+       * If we run it outside AWS (us-west-2 region) and the dataset is cloud hostes we'll use HTTP links
 
     Parameters:
         granules: a list of granules(DataGranule) instances or a list of granule links (HTTP)

earthaccess/search.py

@@ -90,6 +90,23 @@ def keyword(self, text: str) -> Type[CollectionQuery]:
         super().keyword(text)
         return self
 
+    def doi(self, doi: str) -> Type[CollectionQuery]:
+        """Searh datasets by DOI
+
+        ???+ Tip
+            Not all datasets have an associated DOI, also DOI search works
+            only at the dataset level but not the granule (data) level.
+            We need to search by DOI, grab the concept_id and then get the data.
+
+        Parameters:
+            doi (String): DOI of a datasets, e.g. 10.5067/AQR50-3Q7CS
+        """
+        if not isinstance(doi, str):
+            raise TypeError("doi must be of type str")
+
+        self.params["doi"] = doi
+        return self
+
     def parameters(self, **kwargs: Any) -> Type[CollectionQuery]:
         """Provide query parameters as keyword arguments. The keyword needs to match the name
         of the method, and the value should either be the value or a tuple of values.

mkdocs.yml

@@ -43,14 +43,18 @@ plugins:
       execute: False
 
 nav:
-  - Overview: 'index.md'
-  - Tutorials:
-      - 'Basic usage': 'tutorials/demo.ipynb'
-  - How-To:
+  - OVERVIEW: 'index.md'
+  - TUTORIALS:
+      - 'Introducing NASA earthaccess': 'tutorials/demo.ipynb'
       - 'Search and access restricted datasets': 'tutorials/restricted-datasets.ipynb'
-      - 'Search and access on-prem datasets': 'tutorials/onprem.md'
-      - 'Search and cloud-based datasets': 'tutorials/cloud.md'
-  - User Reference:
+  - HOW-TO:
+      - 'Authenticate with Earthdata Login': 'tutorials/authenticate.md'
+      - 'Search data collections using filters': 'tutorials/search-collections.md'
+      - 'Search for granules within a collection using filters': 'tutorials/search-granules.md'
+      - 'Determine if a collection is on-prem or in the cloud': 'tutorials/storage-location.md'
+      - 'Download data from on-prem location': 'tutorials/onprem.md'
+      - 'Direct S3 access - Open/stream files in the cloud': 'tutorials/cloud.md'
+  - USER REFERENCE:
       - API:
           - 'Search and Access': 'user-reference/api/api.md'
       - Modules:
@@ -64,10 +68,10 @@ nav:
             - 'Store': 'user-reference/store/store.md'
         - Auth:
             - 'Auth': 'user-reference/auth/auth.md'
-
       - Glossary:
           - 'NASA Glossary': 'user-reference/glossary/nasa-glossary.md'
           - 'Cloud Computing Terminology': 'user-reference/glossary/cloud-glossary.md'
+
 markdown_extensions:
   - admonition
   - callouts

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "earthaccess"
-version = "0.4.5"
+version = "0.4.6"
 homepage = "https://github.com/nsidc/earthaccess"
 description = "Client library for NASA Earthdata APIs"
 authors = ["earthaccess contributors"]

tests/unit/test_collection_queries.py

@@ -10,3 +10,11 @@ def test_query_can_find_cloud_provider():
     # OBDAAC does not have a cloud provider so it should default to the on prem provider
     query = DataCollections().cloud_hosted(True).daac("OBDAAC")
     assert query.params["provider"] == "OB_DAAC"
+
+
+def test_querybuilder_can_handle_doi():
+    doi = "10.5067/AQR50-3Q7CS"
+    query = DataCollections().doi(doi)
+    assert query.params["doi"] == doi
+    query = DataCollections().cloud_hosted(True).daac("PODAAC").doi(doi)
+    assert query.params["doi"] == doi