Merge branch 'main' into compatibility

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,67 @@
+name: 🐞 Bug
+description: >
+  A bug is an issue that differs from documentation or has unexpected behavior.
+title: "[BUG] {{ title }}"
+labels:
+  - Bug
+  - Needs Triage
+body:
+  - type: checkboxes
+    attributes:
+      label: Is this issue already tracked somewhere, or is this a new report?
+      description: Check if a similar issue has already been reported before submitting a new one.
+      options:
+        - label: I've reviewed existing issues and couldn't find a duplicate for this problem.
+          required: true
+
+  - type: textarea
+    attributes:
+      label: Current Behavior
+      description: A concise description of what you're experiencing.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: A concise description of what you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Steps To Reproduce
+      description: |
+        Steps to Reproduce
+        1. In this environment...
+        2. With this config...
+        3. Run '...'
+        4. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Environment
+      description: |
+        Examples:
+        - **OS**: Ubuntu 20.04
+        - **Python**: 3.11.2
+      value: |
+        - OS:
+        - Python:
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: |
+        Any additional information that might be helpful in resolving this issue, such as:
+        - Error messages or stack traces
+        - Relevant configuration files or code snippets
+
+        Tip: You can attach files or images by clicking this area to highlight it and then dragging files in.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 🌟 Community support
+    url: https://github.com/nsidc/earthaccess/discussions/categories/q-a
+    about: Explore this section to ask questions, share insights, and connect with others about Earthdata access and usage.
+  - name: 💡 Suggest a new feature
+    url: https://github.com/nsidc/earthaccess/discussions/new?category=ideas
+    about: Got a brilliant idea? Share your innovative suggestions to help us make amazing improvements!

.github/workflows/test.yml

@@ -33,6 +33,12 @@ jobs:
           poetry config virtualenvs.create true --local
           poetry config virtualenvs.in-project true --local
           poetry self add setuptools
+      - name: Set up mypy cache
+        uses: actions/cache@v4
+        id: mypy-cache
+        with:
+          path: .mypy_cache
+          key: mypy-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('poetry.lock') }}
       - name: Set up cache
         uses: actions/cache@v4
         id: cache
@@ -44,12 +50,12 @@ jobs:
         run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
       - name: Install Dependencies
         if: ${{ !env.ACT }}
-        run: poetry install
+        run: poetry install --quiet
       - name: Install Dependencies
         if: ${{ env.ACT }}
         # When using `act` to run the workflow locally, the `poetry install` command
         # may fail due to network issues when running multiple Docker containers.
-        run: poetry install || poetry install || poetry install
+        run: poetry install --quiet || poetry install --quiet || poetry install --quiet
       - name: Test
         run: poetry run bash scripts/test.sh
       - name: Upload coverage

.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.0
+    rev: v0.6.3
     hooks:
       - id: ruff
         args: ["--fix", "--exit-non-zero-on-fix"]

CITATION.cff

@@ -26,8 +26,8 @@ keywords:
 url: "https://earthaccess.readthedocs.io"
 repository-code: "https://github.com/nsidc/earthaccess"
 
-version: "0.9.0"
-date-released: "2024-02-28"
+version: "0.10.0"
+date-released: "2024-07-19"
 
 authors:
   - family-names: "Barrett"

README.md

@@ -54,7 +54,30 @@ To install `earthaccess` go to your terminal and install it using `pip`:
 pip install earthaccess
 ```
 
-Visit [our quick start guide](https://earthaccess.readthedocs.io/en/latest/quick-start/) to learn how to install and see a simple example of using `earthaccess`.
+
+### How to access NASA Earth Science data
+
+With _earthaccess_, data is 3 steps away!
+
+```python
+import earthaccess
+
+# 1. Login
+earthaccess.login()
+
+# 2. Search
+results = earthaccess.search_data(
+    short_name='ATL06',  # ATLAS/ICESat-2 L3A Land Ice Height
+    bounding_box=(-10, 20, 10, 50),  # Only include files in area of interest...
+    temporal=("1999-02", "2019-03"),  # ...and time period of interest.
+    count=10
+)
+
+# 3. Access
+files = earthaccess.download(results, "/tmp/my-download-folder")
+```
+
+Visit [our quick start guide](https://earthaccess.readthedocs.io/en/latest/quick-start/) for more details.
 
 
 ## Compatibility

docs/howto/search-granules.md

@@ -16,7 +16,7 @@ results = earthaccess.search_data(
 ### **Searching for data**
 
 Once we have selected our dataset we can search for the data granules using *doi*, *short_name* or *concept_id*.
-If we are not sure or we don't know how to search for a particular dataset, we can start with the ["Introducing NASA earthaccess"](https://nsidc.github.io/earthaccess/tutorials/demo/#querying-for-datasets) tutorial or through the [NASA Earthdata Search portal](https://search.earthdata.nasa.gov/). For a complete list of search parameters we can use visit the extended [API documentation](https://earthaccess.readthedocs.io/en/latest/user-reference/api/api/).
+If we are not sure or we don't know how to search for a particular dataset, we can start with the [NASA Earthdata Search portal](https://search.earthdata.nasa.gov/). For a complete list of search parameters we can use visit the extended [API documentation](https://earthaccess.readthedocs.io/en/latest/user-reference/api/api/).
 
 ```python
 

docs/howto/search-services.md

@@ -0,0 +1,42 @@
+# How to search for services using `earthaccess`
+
+You can search for services associated with a dataset.  Services include a
+back-end processing workflow that transforms or processes the data in some way
+(e.g.  clipping to a spatial extent or converting to a different file format).
+
+`earthaccess` facilitates the retrieval of service metadata via the
+`search_datasets` function.  The results from the `search_datasets` method are
+an enhanced Python dictionary that includes a `services` method which returns
+the metadata for all services associated with a collection.  The service results
+are returned as a Python dictionary.
+
+To search for services, import the earthaccess library and search by dataset
+(you need to know the short name of the dataset which can be found on the
+dataset landing page):
+
+```py
+import earthaccess
+
+datasets = earthaccess.search_datasets(
+    short_name="MUR-JPL-L4-GLOB-v4.1",
+    cloud_hosted=True,
+    temporal=("2024-02-27T00:00:00Z", "2024-02-29T23:59:59Z"),
+)
+```
+
+Parse the service results to return metadata on services available for the dataset.
+
+```py
+for dataset in datasets:
+    print(dataset.services())
+```
+
+Alternatively, you may search directly for services.  For example:
+
+```py
+services = earthaccess.search_services(provider="POCLOUD", keyword="COG")
+```
+
+The keyword arguments supported by the `search_services` function are
+constrained to what the NASA CMR allows, as described in the
+[Service section of the CMR API](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#service).

docs/user-reference/collections/collections-services.md

@@ -0,0 +1,7 @@
+# Documentation for `Collection Services`
+
+::: earthaccess.DataServices
+    options:
+      inherited_members: true
+    show_root_heading: true
+    show_source: false

docs/user_guide/access.md

@@ -6,8 +6,9 @@
 
     We are reorganizing and updating the documentation, so not all pages are complete.  If you are looking for information about accessing data using earthaccess see the
     HOW-TO pages below.
-    [How-to download data](/howto/onprem.md)
-    [Getting Started Tutorial](/tutorials/getting-started.ipynb)
+
+    * [Quick start](../quick-start.md)
+    * [How-to download data](../howto/onprem.md)
 
 ## Downloading data
 

docs/user_guide/authenticate.md

@@ -6,5 +6,6 @@ Introduces the `earthaccess.login` method for managing Earthdata Login and cloud
 
     We are reorganizing and updating the documentation, so not all pages are complete.  If you are looking for information about authenticating using earthaccess see the
     How-Tos and Tutorials in links below.
-    [How-To Authenticate with earthaccess](/howto/authenticate.md)
-    [Getting Started Tutorial](/tutorials/getting-started.ipynb)
+
+    * [Quick start](../quick-start.md)
+    * [How-To Authenticate with earthaccess](../howto/authenticate.md)

docs/user_guide/search.md

@@ -4,8 +4,9 @@
 
     We are reorganizing and updating the documentation, so not all pages are complete.  If you are looking for information about authenticating using earthaccess see the
     How-Tos and Tutorials in links below.
-    [How-To Access Data](/howto/access-data.md)
-    [Getting Started Tutorial](/tutorials/getting-started.ipynb)
+
+    * [Quick start](../quick-start.md)
+    * [How-To Access Data](../howto/access-data.md)
 
 ## `search_datasets`
 

earthaccess/__init__.py

@@ -10,16 +10,19 @@
     get_fsspec_https_session,
     get_requests_https_session,
     get_s3_credentials,
+    get_s3_filesystem,
     get_s3fs_session,
     granule_query,
     login,
     open,
     search_data,
     search_datasets,
+    search_services,
 )
 from .auth import Auth
 from .kerchunk import consolidate_metadata
 from .search import DataCollections, DataGranules
+from .services import DataServices
 from .store import Store
 from .system import PROD, UAT
 
@@ -30,10 +33,12 @@
     "login",
     "search_datasets",
     "search_data",
+    "search_services",
     "get_requests_https_session",
     "get_fsspec_https_session",
     "get_s3fs_session",
     "get_s3_credentials",
+    "get_s3_filesystem",
     "get_edl_token",
     "granule_query",
     "collection_query",
@@ -43,6 +48,7 @@
     # search.py
     "DataGranules",
     "DataCollections",
+    "DataServices",
     # auth.py
     "Auth",
     # store.py
@@ -68,26 +74,24 @@ def __getattr__(name):  # type: ignore
     """
     global _auth, _store
 
-    if name == "__auth__" or name == "__store__":
-        with _lock:
-            if not _auth.authenticated:
-                for strategy in ["environment", "netrc"]:
-                    try:
-                        _auth.login(strategy=strategy)
-                    except Exception as e:
+    if name not in ["__auth__", "__store__"]:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    with _lock:
+        if not _auth.authenticated:
+            for strategy in ["environment", "netrc"]:
+                try:
+                    _auth.login(strategy=strategy)
+
+                    if _auth.authenticated:
+                        _store = Store(_auth)
                         logger.debug(
-                            f"An error occurred during automatic authentication with {strategy=}: {str(e)}"
+                            f"Automatic authentication with {strategy=} was successful"
                         )
-                        continue
-                    else:
-                        if not _auth.authenticated:
-                            continue
-                        else:
-                            _store = Store(_auth)
-                            logger.debug(
-                                f"Automatic authentication with {strategy=} was successful"
-                            )
-                            break
-            return _auth if name == "__auth__" else _store
-    else:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+                        break
+                except Exception as e:
+                    logger.debug(
+                        f"An error occurred during automatic authentication with {strategy=}: {str(e)}"
+                    )
+
+        return _auth if name == "__auth__" else _store