Skip to content

Commit

Permalink
further docstring cleanup, grammar
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielfromearth
danielfromearth committed Feb 7, 2024
1 parent 9aea057 commit ebb15a1
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 41 deletions.
17 changes: 8 additions & 9 deletions earthaccess/api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down
8 changes: 4 additions & 4 deletions earthaccess/results.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 7 additions & 6 deletions earthaccess/search.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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)
Expand Down
46 changes: 24 additions & 22 deletions earthaccess/store.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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")

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"):
Expand Down Expand Up @@ -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")
Expand Down

0 comments on commit ebb15a1

Please sign in to comment.