Skip to content

Commit

Permalink
further docstring cleanup in api.py and auth.py
Browse files Browse the repository at this point in the history
  • Loading branch information
@danielfromearth
danielfromearth committed Feb 7, 2024
1 parent 2e57d2f commit 8b6e58b
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 27 deletions.
35 changes: 18 additions & 17 deletions earthaccess/api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@


def _normalize_location(location: Optional[str]) -> Optional[str]:
"""Handle user-provided `daac` and `provider` values
"""Handle user-provided `daac` and `provider` values.
These values must have a capital letter as the first character
followed by capital letters, numbers, or an underscore. Here we
Expand All @@ -40,7 +40,7 @@ def search_datasets(
kwargs (Dict):
arguments to CMR:
* **keyword**: case insensitive and support wild cards ? and *,
* **keyword**: case-insensitive and support wildcards ? and *,
* **short_name**: e.g. ATL08
* **doi**: DOI for a dataset
* **daac**: e.g. NSIDC or PODAAC
Expand Down Expand Up @@ -125,7 +125,7 @@ def search_data(


def login(strategy: str = "all", persist: bool = False) -> Auth:
"""Authenticate with Earthdata login (https://urs.earthdata.nasa.gov/)
"""Authenticate with Earthdata login (https://urs.earthdata.nasa.gov/).
Parameters:
strategy:
Expand Down Expand Up @@ -202,7 +202,7 @@ def open(
Parameters:
granules: a list of granule instances **or** list of URLs, e.g. `s3://some-granule`.
If a list of URLs is passed, we need to specify the data provider.
provider: e.g. POCLOUD, NSIDC_CPRD etc.
provider: e.g. POCLOUD, NSIDC_CPRD, etc.
Returns:
a list of s3fs "file pointers" to s3 files.
Expand All @@ -217,14 +217,14 @@ def get_s3_credentials(
provider: Optional[str] = None,
results: Optional[List[earthaccess.results.DataGranule]] = None,
) -> Dict[str, Any]:
"""Returns temporary (1 hour) credentials for direct access to NASA S3 buckets, we can
use the daac name, the provider or a list of results from earthaccess.search_data()
if we use results earthaccess will use the metadata on the response to get the credentials,
this is useful for missions that do not use the same endpoint as their DAACs e.g. SWOT
"""Returns temporary (1 hour) credentials for direct access to NASA S3 buckets. We can
use the daac name, the provider, or a list of results from earthaccess.search_data().
If we use results, earthaccess will use the metadata on the response to get the credentials,
which is useful for missions that do not use the same endpoint as their DAACs, e.g. SWOT.
Parameters:
daac: a DAAC short_name like NSIDC or PODAAC etc
provider: if we know the provider for the DAAC e.g. POCLOUD, LPCLOUD etc.
daac: a DAAC short_name like NSIDC or PODAAC, etc.
provider: if we know the provider for the DAAC, e.g. POCLOUD, LPCLOUD etc.
results: List of results from search_data()
Returns:
Expand All @@ -239,7 +239,7 @@ def get_s3_credentials(


def collection_query() -> Type[CollectionQuery]:
"""Returns a query builder instance for NASA collections (datasets)
"""Returns a query builder instance for NASA collections (datasets).
Returns:
a query builder instance for data collections.
Expand All @@ -265,7 +265,7 @@ def granule_query() -> Type[GranuleQuery]:


def get_fsspec_https_session() -> AbstractFileSystem:
"""Returns a fsspec session that can be used to access datafiles across many different DAACs
"""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
Expand All @@ -286,8 +286,8 @@ def get_fsspec_https_session() -> AbstractFileSystem:


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
"""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
require authentication with NASA EDL.
Returns:
Expand All @@ -313,11 +313,12 @@ def get_s3fs_session(
provider: Optional[str] = None,
results: Optional[earthaccess.results.DataGranule] = None,
) -> s3fs.S3FileSystem:
"""Returns a fsspec s3fs file session for direct access when we are in us-west-2
"""Returns a fsspec s3fs file session for direct access when we are in us-west-2.
Parameters:
daac: Any DAAC short name e.g. NSIDC, GES_DISC
provider: Each DAAC can have a cloud provider, if the DAAC is specified, there is no need to use provider
provider: Each DAAC can have a cloud provider.
If the DAAC is specified, there is no need to use provider.
results: A list of results from search_data(), earthaccess will use the metadata form CMR to obtain the S3 Endpoint
Returns:
Expand All @@ -335,7 +336,7 @@ def get_s3fs_session(


def get_edl_token() -> str:
"""Returns the current token used for EDL
"""Returns the current token used for EDL.
Returns:
EDL token
Expand Down
17 changes: 7 additions & 10 deletions earthaccess/auth.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,12 @@ def login(self, strategy: str = "netrc", persist: bool = False) -> Any:
"""Authenticate with Earthdata login.
Parameters:
strategy: authentication method.
strategy:
authentication method.
"interactive": enter username and password.
"netrc": (default) retrieve username and password from ~/.netrc.
"environment": retrieve username and password from $EARTHDATA_USERNAME and $EARTHDATA_PASSWORD.
* **"interactive"**: enter username and password.
* **"netrc"**: (default) retrieve username and password from ~/.netrc.
* **"environment"**: retrieve username and password from $EARTHDATA_USERNAME and $EARTHDATA_PASSWORD.
persist: will persist credentials in a .netrc file
Returns:
Expand All @@ -89,7 +88,6 @@ def login(self, strategy: str = "netrc", persist: bool = False) -> Any:

def refresh_tokens(self) -> bool:
"""Refresh CMR tokens.
Tokens are used to do authenticated queries on CMR for restricted and early access datasets.
This method renews the tokens to make sure we can query the collections allowed to our EDL user.
"""
Expand Down Expand Up @@ -149,13 +147,12 @@ def get_s3_credentials(
easier way is to use the DAAC short name. provider is optional if we know it.
Parameters:
provider: A valid cloud provider, each DAAC has a provider code for their cloud distributions
daac: the name of a NASA DAAC, i.e. NSIDC or PODAAC
provider: A valid cloud provider. Each DAAC has a provider code for their cloud distributions.
endpoint: getting the credentials directly from the S3Credentials URL
Returns:
A Python dictionary with the temporary AWS S3 credentials
"""
if self.authenticated:
session = SessionWithHeaderRedirection(self.username, self.password)
Expand Down Expand Up @@ -205,7 +202,7 @@ def get_session(self, bearer_token: bool = True) -> requests.Session:
"""Returns a new request session instance.
Parameters:
bearer_token: boolean, include bearer token
bearer_token: whether to include bearer token
Returns:
class Session instance with Auth and bearer token headers
Expand Down

0 comments on commit 8b6e58b

Please sign in to comment.