Clarify that temporal and bbox args must be tuples in docstrings, fix docstring formatting

binder/environment-dev.yml

@@ -10,6 +10,16 @@ dependencies:
  - ipyleaflet>=0.13
  - h5netcdf>=0.11
  - cartopy
+
+ - mkdocs>=1.2
+ - mkdocs-material>=7.1,<9.0
+ - markdown-include>=0.6
+ - mkdocstrings>=0.19.0
+ - mkdocstrings-python
+ - mkdocs-jupyter>=0.19.0
+ - pymdown-extensions>=9.2
+
  - pip
  - pip:
  - poetry
+ - markdown-callouts>=0.2.0

earthaccess/api.py

@@ -13,7 +13,7 @@
 from .utils import _validation as validate
 
 
-def _normalize_location(location: Union[str, None]) -> Union[str, None]:
+def _normalize_location(location: Optional[str]) -> Optional[str]:
  """Handle user-provided `daac` and `provider` values
 
  These values must have a capital letter as the first character
@@ -31,32 +31,29 @@ def _normalize_location(location: Union[str, None]) -> Union[str, None]:
 def search_datasets(
  count: int = -1, **kwargs: Any
 ) -> List[earthaccess.results.DataCollection]:
- """Search datasets using NASA's CMR
+ """Search datasets using NASA's CMR.
 
  [https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
 
  Parameters:
-
- count (Integer): Number of records to get, -1 = all
- kwargs (Dict): arguments to CMR:
+ count: Number of records to get, -1 = all
+ kwargs (Dict):
+   arguments to CMR:
 
  * **keyword**: case insensitive and support wild cards ? and *,
-
  * **short_name**: e.g. ATL08
-
  * **doi**: DOI for a dataset
-
  * **daac**: e.g. NSIDC or PODAAC
-
  * **provider**: particular to each DAAC, e.g. POCLOUD, LPDAAC etc.
+ * **temporal**: a tuple representing temporal bounds in the form
+ `("yyyy-mm-dd", "yyyy-mm-dd")`
+ * **bounding_box**: a tuple representing spatial bounds in the form
+ `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`
 
- * **temporal**: ("yyyy-mm-dd", "yyyy-mm-dd")
-
- * **bounding_box**: (lower_left_lon, lower_left_lat ,
- upper_right_lon, upper_right_lat)
  Returns:
- an list of DataCollection results that can be used to get
- information such as concept_id, doi, etc. about a dataset.
+ a list of DataCollection results that can be used to get information about a
+ dataset, e.g. concept_id, doi, etc.
+
  Examples:
  ```python
  datasets = earthaccess.search_datasets(
@@ -89,27 +86,24 @@ def search_data(
  [https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
 
  Parameters:
-
- count (Integer): Number of records to get, -1 = all
- kwargs (Dict): arguments to CMR:
+ count: Number of records to get, -1 = all
+ kwargs (Dict):
+   arguments to CMR:
 
  * **short_name**: dataset short name e.g. ATL08
-
  * **version**: dataset version
-
  * **doi**: DOI for a dataset
-
  * **daac**: e.g. NSIDC or PODAAC
-
  * **provider**: particular to each DAAC, e.g. POCLOUD, LPDAAC etc.
+ * **temporal**: a tuple representing temporal bounds in the form
+ `("yyyy-mm-dd", "yyyy-mm-dd")`
+ * **bounding_box**: a tuple representing spatial bounds in the form
+ `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`
 
- * **temporal**: ("yyyy-mm-dd", "yyyy-mm-dd")
-
- * **bounding_box**: (lower_left_lon, lower_left_lat ,
- upper_right_lon, upper_right_lat)
  Returns:
- Granules: a list of DataGranules that can be used to access
- the granule files by using `download()` or `open()`.
+ a list of DataGranules that can be used to access the granule files by using
+ `download()` or `open()`.
+
  Examples:
  ```python
  datasets = earthaccess.search_data(
@@ -134,17 +128,15 @@ def login(strategy: str = "all", persist: bool = False) -> Auth:
  """Authenticate with Earthdata login (https://urs.earthdata.nasa.gov/)
 
  Parameters:
+ strategy:
+ authentication method.
 
- strategy (String): authentication method.
-
- "all": (default) try all methods until one works
-
- "interactive": enter username and password.
-
- "netrc": retrieve username and password from ~/.netrc.
+ * **"all"**: (default) try all methods until one works
+ * **"interactive"**: enter username and password.
+ * **"netrc"**: 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
 
- "environment": retrieve username and password from $EARTHDATA_USERNAME and $EARTHDATA_PASSWORD.
- persist (Boolean): will persist credentials in a .netrc file
  Returns:
  an instance of Auth.
  """
@@ -168,7 +160,7 @@ def login(strategy: str = "all", persist: bool = False) -> Auth:
 
 def download(
  granules: Union[DataGranule, List[DataGranule], str, List[str]],
- local_path: Union[str, None],
+ local_path: Optional[str],
  provider: Optional[str] = None,
  threads: int = 8,
 ) -> List[str]:
@@ -208,8 +200,10 @@ def open(
  hosted on S3 or HTTPS by third party libraries like xarray.
 
  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 e.g. POCLOUD, NSIDC_CPRD etc.
+ 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 e.g. POCLOUD, NSIDC_CPRD etc.
+
  Returns:
  a list of s3fs "file pointers" to s3 files.
  """
@@ -229,9 +223,10 @@ def get_s3_credentials(
  this is useful for missions that do not use the same endpoint as their DAACs e.g. SWOT
 
  Parameters:
- daac (String): a DAAC short_name like NSIDC or PODAAC etc
- provider (String: if we know the provider for the DAAC e.g. POCLOUD, LPCLOUD etc.
- results (list[earthaccess.results.DataGranule]): List of results from search_data()
+ 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:
  a dictionary with S3 credentials for the DAAC or provider
  """
@@ -246,10 +241,8 @@ def get_s3_credentials(
 def collection_query() -> Type[CollectionQuery]:
  """Returns a query builder instance for NASA collections (datasets)
 
- Parameters:
- cloud_hosted (Boolean): initializes the query builder for cloud hosted collections.
  Returns:
- class earthaccess.DataCollections: a query builder instance for data collections.
+ a query builder instance for data collections.
  """
  if earthaccess.__auth__.authenticated:
  query_builder = DataCollections(earthaccess.__auth__)
@@ -261,11 +254,8 @@ class earthaccess.DataCollections: a query builder instance for data collections
 def granule_query() -> Type[GranuleQuery]:
  """Returns a query builder instance for data granules
 
- Parameters:
- cloud_hosted (Boolean): initializes the query builder for a particular DOI
- if we have it.
  Returns:
- class earthaccess.DataGranules: a query builder instance for data granules.
+ a query builder instance for data granules.
  """
  if earthaccess.__auth__.authenticated:
  query_builder = DataGranules(earthaccess.__auth__)
@@ -278,7 +268,7 @@ def get_fsspec_https_session() -> AbstractFileSystem:
  """Returns a fsspec session that can be used to access datafiles across many different DAACs
 
  Returns:
- class AbstractFileSystem: an fsspec instance able to access data across DAACs
+ an fsspec instance able to access data across DAACs
 
  Examples:
  ```python
@@ -301,7 +291,7 @@ def get_requests_https_session() -> requests.Session:
  require authentication with NASA EDL.
 
  Returns:
- class requests.Session: an authenticated requests Session instance.
+ an authenticated requests Session instance.
 
  Examples:
  ```python
@@ -326,12 +316,12 @@ def get_s3fs_session(
  """Returns a fsspec s3fs file session for direct access when we are in us-west-2
 
  Parameters:
- daac (String): Any DAAC short name e.g. NSIDC, GES_DISC
- provider (String): Each DAAC can have a cloud provider, if the DAAC is specified, there is no need to use provider
- results (list[class earthaccess.results.DataGranule]): A list of results from search_data(), earthaccess will use the metadata form CMR to obtain the S3 Endpoint
+ 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
+ results: A list of results from search_data(), earthaccess will use the metadata form CMR to obtain the S3 Endpoint
 
  Returns:
- class s3fs.S3FileSystem: an authenticated s3fs session valid for 1 hour
+ an authenticated s3fs session valid for 1 hour
  """
  daac = _normalize_location(daac)
  provider = _normalize_location(provider)
@@ -348,8 +338,7 @@ def get_edl_token() -> str:
  """Returns the current token used for EDL
 
  Returns:
- str: EDL token
-
+ EDL token
  """
  token = earthaccess.__auth__.token
  return token