further docstring cleanup, grammar

danielfromearth · danielfromearth · commit ebb15a16cb66 · 2024-02-07T16:23:33.000-05:00
diff --git a/earthaccess/api.py b/earthaccess/api.py
@@ -40,7 +40,7 @@ def search_datasets(
         kwargs (Dict):
             arguments to CMR:
 
-            * **keyword**: case-insensitive and support wildcards ? and *,
+            * **keyword**: case-insensitive and supports wildcards ? and *
             * **short_name**: e.g. ATL08
             * **doi**: DOI for a dataset
             * **daac**: e.g. NSIDC or PODAAC
@@ -51,7 +51,7 @@ def search_datasets(
               `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`
 
     Returns:
-        a list of DataCollection results that can be used to get information about a
+        A list of DataCollection results that can be used to get information about a
             dataset, e.g. concept_id, doi, etc.
 
     Examples:
@@ -90,7 +90,7 @@ def search_data(
         kwargs (Dict):
             arguments to CMR:
 
-            * **short_name**: dataset short name e.g. ATL08
+            * **short_name**: dataset short name, e.g. ATL08
             * **version**: dataset version
             * **doi**: DOI for a dataset
             * **daac**: e.g. NSIDC or PODAAC
@@ -173,7 +173,7 @@ def download(
     Parameters:
         granules: a granule, list of granules, a granule link (HTTP), or a list of granule links (HTTP)
         local_path: local directory to store the remote data granules
-        provider: if we download a list of URLs we need to specify the provider.
+        provider: if we download a list of URLs, we need to specify the provider.
         threads: parallel number of threads to use to download the files, adjust as necessary, default = 8
 
     Returns:
@@ -269,7 +269,7 @@ def get_fsspec_https_session() -> AbstractFileSystem:
     """Returns a fsspec session that can be used to access datafiles across many different DAACs.
 
     Returns:
-        an fsspec instance able to access data across DAACs
+        An fsspec instance able to access data across DAACs.
 
     Examples:
         ```python
@@ -280,19 +280,18 @@ def get_fsspec_https_session() -> AbstractFileSystem:
         with fs.open(DAAC_GRANULE) as f:
             f.read(10)
         ```
-
     """
     session = earthaccess.__store__.get_fsspec_session()
     return session
 
 
 def get_requests_https_session() -> requests.Session:
     """Returns a requests Session instance with an authorized bearer token.
-    This is useful to make requests to restricted URLs like data granules or services that
+    This is useful for making requests to restricted URLs, such as data granules or services that
     require authentication with NASA EDL.
 
     Returns:
-        an authenticated requests Session instance.
+        An authenticated requests Session instance.
 
     Examples:
         ```python
@@ -324,7 +323,7 @@ def get_s3fs_session(
             `earthaccess` will use the metadata from CMR to obtain the S3 Endpoint.
 
     Returns:
-        an authenticated s3fs session valid for 1 hour
+        An authenticated s3fs session valid for 1 hour.
     """
     daac = _normalize_location(daac)
     provider = _normalize_location(provider)
diff --git a/earthaccess/results.py b/earthaccess/results.py
@@ -310,12 +310,12 @@ def data_links(
                     # we have the s3 links so we return those
                     return s3_links
             else:
-                # Even though we are in us-west-2, the user wants the HTTPS links
-                # used in region they are S3 signed links from TEA
-                # https://github.com/asfadmin/thin-egress-app
+                # Even though we are in us-west-2, the user wants the HTTPS links used in-region.
+                # They are S3 signed links from TEA.
+                # <https://github.com/asfadmin/thin-egress-app>
                 return https_links
         else:
-            # we are not in region
+            # we are not in-region
             if access == "direct":
                 # maybe the user wants to collect S3 links and use them later
                 # from the cloud
diff --git a/earthaccess/search.py b/earthaccess/search.py
@@ -428,15 +428,16 @@ def orbit_number(self, orbit1: int, orbit2: int) -> Type[GranuleQuery]:
         return self
 
     def cloud_hosted(self, cloud_hosted: bool = True) -> Type[CollectionQuery]:
-        """Only match granules that are hosted in the cloud. This is valid for public
-        collections and if we are using the short_name parameter. Concept-Id is unambiguous.
+        """Only match granules that are hosted in the cloud.
+        This is valid for public collections and when using the short_name parameter.
+        Concept-Id is unambiguous.
 
         ???+ Tip
-            Cloud hosted collections can be public or restricted.
-            Restricted collections will not be matched using this parameter
+            Cloud-hosted collections can be public or restricted.
+            Restricted collections will not be matched using this parameter.
 
         Parameters:
-            cloud_hosted (Boolean): True to require granules only be online
+            cloud_hosted: True to require granules only be online
         """
         if not isinstance(cloud_hosted, bool):
             raise TypeError("cloud_hosted must be of type bool")
@@ -455,7 +456,7 @@ def granule_name(self, granule_name: str) -> Type[CollectionQuery]:
 
         ???+ Tip
             We can use wildcards on a granule name to further refine our search,
-            e.g. MODGRNLD.*.daily.*
+            e.g. `MODGRNLD.*.daily.*`.
 
         Parameters:
             granule_name: granule name (accepts wildcards)
diff --git a/earthaccess/store.py b/earthaccess/store.py
@@ -155,21 +155,22 @@ def _running_in_us_west_2(self) -> bool:
             return False
 
         if resp.status_code == 200 and b"us-west-2" == resp.content:
-            # On AWS in region us-west-2
+            # On AWS, in region us-west-2
             return True
         return False
 
     def set_requests_session(
         self, url: str, method: str = "get", bearer_token: bool = False
     ) -> None:
         """Sets up a `requests` session with bearer tokens that are used by CMR.
-        Mainly used to get the authentication cookies from different DAACs and URS
-        This HTTPS session can be used to download granules if we want to use a direct, lower level API
+        Mainly used to get the authentication cookies from different DAACs and URS.
+        This HTTPS session can be used to download granules if we want to use a direct,
+        lower level API.
 
         Parameters:
             url: used to test the credentials and populate the class auth cookies
-            method: HTTP method to test. default: "GET"
-            bearer_token: if true will be used for authenticated queries on CMR
+            method: HTTP method to test, default: "GET"
+            bearer_token: if true, will be used for authenticated queries on CMR
 
         Returns:
             fsspec HTTPFileSystem (aiohttp client session)
@@ -203,7 +204,7 @@ def get_s3fs_session(
         """Returns a s3fs instance for a given cloud provider / DAAC.
 
         Parameters:
-            daac: any of the DAACs e.g. NSIDC, PODAAC
+            daac: any of the DAACs, e.g. NSIDC, PODAAC
             provider: a data provider if we know them, e.g. PODAAC -> POCLOUD
             endpoint: pass the URL for the credentials directly
 
@@ -262,7 +263,8 @@ def get_s3fs_session(
     @lru_cache
     def get_fsspec_session(self) -> fsspec.AbstractFileSystem:
         """Returns a fsspec HTTPS session with bearer tokens that are used by CMR.
-        This HTTPS session can be used to download granules if we want to use a direct, lower level API
+        This HTTPS session can be used to download granules if we want to use a direct,
+        lower level API.
 
         Returns:
             fsspec HTTPFileSystem (aiohttp client session)
@@ -279,7 +281,8 @@ def get_fsspec_session(self) -> fsspec.AbstractFileSystem:
 
     def get_requests_session(self, bearer_token: bool = True) -> requests.Session:
         """Returns a requests HTTPS session with bearer tokens that are used by CMR.
-        This HTTPS session can be used to download granules if we want to use a direct, lower level API
+        This HTTPS session can be used to download granules if we want to use a direct,
+        lower level API.
 
         Parameters:
             bearer_token: if true, will be used for authenticated queries on CMR
@@ -303,7 +306,7 @@ def open(
             provider: an option
 
         Returns:
-            a list of s3fs "file pointers" to s3 files.
+            A list of s3fs "file pointers" to s3 files.
         """
         if len(granules):
             return self._open(granules, provider)
@@ -324,7 +327,7 @@ def _open(
             provider: an option
 
         Returns:
-            a list of s3fs "file pointers" to s3 files.
+            A list of s3fs "file pointers" to s3 files.
         """
         raise NotImplementedError("granules should be a list of DataGranule or URLs")
 
@@ -454,11 +457,10 @@ def get(
              the data will be effectively downloaded to a local directory.
 
         Parameters:
-            granules: a list of granules(DataGranule) instances or a list of granule links (HTTP)
-            local_path: local directory to store the remote data granules
-            access: direct or on_prem, if set it will use it for the access method.
-            threads: parallel number of threads to use to download the files;
-                adjust as necessary, default = 8
+            granules: A list of granules(DataGranule) instances or a list of granule links (HTTP).
+            local_path: Local directory to store the remote data granules.
+            threads: Parallel number of threads to use to download the files;
+                adjust as necessary, default = 8.
 
         Returns:
             List of downloaded files
@@ -493,10 +495,10 @@ def _get(
              the data will be effectively downloaded to a local directory.
 
         Parameters:
-            granules: a list of granules(DataGranule) instances or a list of granule links (HTTP)
-            local_path: local directory to store the remote data granules
-            access: direct or on_prem, if set it will use it for the access method.
-            threads: parallel number of threads to use to download the files, adjust as necessary, default = 8
+            granules: A list of granules (DataGranule) instances or a list of granule links (HTTP).
+            local_path: Local directory to store the remote data granules
+            threads: Parallel number of threads to use to download the files;
+                adjust as necessary, default = 8.
 
         Returns:
             None
@@ -548,7 +550,7 @@ def _get_granules(
         cloud_hosted = granules[0].cloud_hosted
         access = "direct" if (cloud_hosted and self.in_region) else "external"
         data_links = list(
-            # we are not in region
+            # we are not in-region
             chain.from_iterable(
                 granule.data_links(access=access, in_region=self.in_region)
                 for granule in granules
@@ -587,7 +589,7 @@ def _download_file(self, url: str, directory: str) -> str:
             directory: local directory
 
         Returns:
-            a local filepath or an exception
+            A local filepath or an exception.
         """
         # If the get data link is an Opendap location
         if "opendap" in url and url.endswith(".html"):
@@ -628,7 +630,7 @@ def _download_onprem_granules(
                 adjust as necessary, default = 8
 
         Returns:
-            a list of local filepaths to which the files were downloaded
+            A list of local filepaths to which the files were downloaded.
         """
         if urls is None:
             raise ValueError("The granules didn't provide a valid GET DATA link")
