Skip to content

Commit

Permalink
updated more docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@dchaddock
dchaddock committed Jan 23, 2025
1 parent ca941b8 commit e174e47
Show file tree
Hide file tree
Showing 10 changed files with 261 additions and 153 deletions.
113 changes: 75 additions & 38 deletions pyaurorax/search/ephemeris/classes/search.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,25 @@ class EphemerisSearch:
Note: At least one search criteria from programs, platforms, or instrument_types
must be specified.
Args:
start: start timestamp of the search (inclusive)
end: end timestamp of the search (inclusive)
programs: list of programs to search through, defaults to None
platforms: list of platforms to search through, defaults to None
instrument_types: list of instrument types to search through, defaults to None
metadata_filters: list of dictionaries describing metadata keys and
values to filter on, defaults to None
Attributes:
start (datetime.datetime):
start timestamp of the search (inclusive)
end (datetime.datetime):
end timestamp of the search (inclusive)
programs (List[str]):
list of programs to search through, defaults to None
platforms (List[str]):
list of platforms to search through, defaults to None
instrument_types (List[str]):
list of instrument types to search through, defaults to None
metadata_filters (List[Dict]):
list of dictionaries describing metadata keys and values to filter on, defaults
to None
e.g. {
"key": "string",
Expand All @@ -55,20 +66,43 @@ class EphemerisSearch:
"string"
]
}
metadata_filters_logical_operator: the logical operator to use when
evaluating metadata filters (either 'AND' or 'OR'), defaults
to "AND"
response_format: JSON representation of desired data response format
request: AuroraXResponse object returned when the search is executed
request_id: unique ID assigned to the request by the AuroraX API
request_url: unique URL assigned to the request by the AuroraX API
executed: indicates if the search has been executed/started
completed: indicates if the search has finished
data_url: the URL where data is accessed
query: the query for this request as JSON
status: the status of the query
data: the ephemeris records found
logs: all log messages outputted by the AuroraX API for this request
metadata_filters_logical_operator (str):
the logical operator to use when evaluating metadata filters (either `AND` or `OR`),
defaults to `AND`
response_format (Dict):
JSON representation of desired data response format
request (AuroraXResponse):
AuroraXResponse object returned when the search is executed
request_id (str):
unique ID assigned to the request by the AuroraX API
request_url (str):
unique URL assigned to the request by the AuroraX API
executed (bool):
indicates if the search has been executed/started
completed (bool):
indicates if the search has finished
data_url (str):
the URL where data is accessed
query (Dict):
the query for this request as JSON
status ():
the status of the query
data:
the ephemeris records found
logs:
all log messages outputted by the AuroraX API for this request
"""

__STANDARD_POLLING_SLEEP_TIME: float = 1.0
Expand Down Expand Up @@ -221,8 +255,9 @@ def update_status(self, status: Optional[Dict] = None) -> None:
Update the status of this ephemeris search request
Args:
status: the previously-retrieved status of this request (include
to avoid requesting it from the API again), defaults to None
status (Dict):
the previously-retrieved status of this request (include to avoid requesting it
from the API again), defaults to None
"""
# get the status if it isn't passed in
if (status is None):
Expand All @@ -243,8 +278,7 @@ def update_status(self, status: Optional[Dict] = None) -> None:

def check_for_data(self) -> bool:
"""
Check to see if data is available for this ephemeris
search request
Check to see if data is available for this ephemeris search request
Returns:
True if data is available, else False
Expand Down Expand Up @@ -278,14 +312,14 @@ def get_data(self) -> None:

def wait(self, poll_interval: float = __STANDARD_POLLING_SLEEP_TIME, verbose: bool = False) -> None:
"""
Block and wait for the request to complete and data is
available for retrieval
Block and wait for the request to complete and data is available for retrieval
Args:
poll_interval: time in seconds to wait between polling attempts,
defaults to pyaurorax.requests.STANDARD_POLLING_SLEEP_TIME
verbose: output poll times and other progress messages, defaults
to False
poll_interval (float):
time in seconds to wait between polling attempts, defaults to 1 second
verbose (bool):
output poll times and other progress messages, defaults to False
"""
url = "%s/%s" % (self.aurorax_obj.api_base_url, self.aurorax_obj.search.api.URL_SUFFIX_EPHEMERIS_REQUEST.format(self.request_id))
self.update_status(requests_wait_for_data(self.aurorax_obj, url, poll_interval, verbose))
Expand All @@ -300,12 +334,15 @@ def cancel(self, wait: bool = False, poll_interval: float = __STANDARD_POLLING_S
the polling time using the 'poll_interval' parameter.
Args:
wait: wait until the cancellation request has been
completed (may wait for several minutes)
poll_interval: seconds to wait between polling
calls, defaults to STANDARD_POLLING_SLEEP_TIME.
verbose: output poll times and other progress messages, defaults
to False
wait (bool):
wait until the cancellation request has been completed (may wait for
several minutes)
poll_interval (float):
seconds to wait between polling calls, defaults to 1 second.
verbose (bool):
output poll times and other progress messages, defaults to False
Returns:
1 on success
Expand Down
16 changes: 12 additions & 4 deletions pyaurorax/search/metadata/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,14 @@ def validate(self, schema: List[Dict], record: Dict, quiet: Optional[bool] = Fal
key names match and there aren't fewer or more keys than expected.
Args:
schema: the metadata schema to validate against
record: metadata record to validate
schema (List[Dict]):
the metadata schema to validate against
record (Dict):
metadata record to validate
quiet (bool):
suppress any stdout output
Returns:
True if the metadata record is valid, False if it is not
Expand All @@ -55,7 +61,8 @@ def get_ephemeris_schema(self, identifier: int) -> List[Dict]:
Retrieve the ephemeris metadata schema for a data source
Args:
identifier: the AuroraX data source ID
identifier (int):
the AuroraX data source ID
Returns:
the ephemeris metadata schema for the data source
Expand All @@ -67,7 +74,8 @@ def get_data_products_schema(self, identifier: int) -> List[Dict]:
Retrieve the data products metadata schema for a data source
Args:
identifier: the AuroraX data source ID
identifier (int):
the AuroraX data source ID
Returns:
the data products metadata schema for the data source
Expand Down
93 changes: 60 additions & 33 deletions pyaurorax/search/requests/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ def get_status(self, request_url: str) -> Dict:
Retrieve the status of a request
Args:
request_url: the URL of the request information
request_url (str):
the URL of the request information
Returns:
the status information for the request
Expand All @@ -61,10 +62,14 @@ def get_data(self, data_url: str, response_format: Optional[Dict] = None, skip_s
Retrieve the data for a request
Args:
data_url: the URL for the data of a request,
response_format: the response format to send as post data, defaults
to None
skip_serializing: skip any object serializing, defaults to False
data_url (str):
the URL for the data of a request,
response_format (Dict):
the response format to send as post data, defaults to None
skip_serializing (bool):
skip any object serializing, defaults to False
Raises:
pyaurorax.exceptions.AuroraXDataRetrievalError: error retrieving data
Expand All @@ -79,7 +84,8 @@ def get_logs(self, request_url: str) -> List:
Retrieve the logs for a request
Args:
request_url: the URL of the request information
request_url (str):
the URL of the request information
Returns:
the log messages for the request
Expand All @@ -91,10 +97,14 @@ def wait_for_data(self, request_url: str, poll_interval: float = __STANDARD_POLL
Block and wait for the data to be made available for a request
Args:
request_url: the URL of the request information
poll_interval: seconds to wait between polling calls, defaults
to STANDARD_POLLING_SLEEP_TIME
verbose: output poll times and other progress messages, defaults to False
request_url (str):
the URL of the request information
poll_interval (float):
seconds to wait between polling calls, defaults to STANDARD_POLLING_SLEEP_TIME
verbose (bool):
output poll times and other progress messages, defaults to False
Returns:
the status information for the request
Expand All @@ -111,13 +121,18 @@ def cancel(self, request_url: str, wait: bool = False, poll_interval: float = __
the polling time using the 'poll_interval' parameter.
Args:
request_url: the URL string of the request to be canceled
wait: set to True to block until the cancellation request
has been completed (may wait for several minutes)
poll_interval: seconds to wait between polling
calls, defaults to STANDARD_POLLING_SLEEP_TIME.
verbose: if True then output poll times and other
progress, defaults to False
request_url (str):
the URL string of the request to be canceled
wait (bool):
set to True to block until the cancellation request has been completed (may
wait for several minutes)
poll_interval (float):
seconds to wait between polling calls, defaults to STANDARD_POLLING_SLEEP_TIME.
verbose (bool):
if True then output poll times and other progress, defaults to False
Returns:
0 on success
Expand All @@ -141,19 +156,31 @@ def list(self,
Retrieve a list of search requests matching certain criteria. Administrators only.
Args:
search_type: the type of search request, valid values are 'conjunction',
'ephemeris', or 'data_product'. Exclusion of value will return all
search requests of any type, defaults to None
active: return searches that are currently active or not, exclude for
both, defaults to None
start: start timestamp for narrowing down search timeframes, defaults to None
end: end timestamp for narrowing down search timeframes, defaults to None
file_size: filter by result file size, measured in KB, defaults to None
result_count: filter by result count, defaults to None
query_duration: filter by query duration, measured in milliseconds, defaults
to None
error_condition: filter by if an error occurred or not, exclude for both,
defaults to None
search_type (str):
the type of search request, valid values are 'conjunction', 'ephemeris', or
'data_product'. Exclusion of value will return all search requests of any
type, defaults to None
active (bool):
return searches that are currently active or not, exclude for both, defaults to None
start (datetime.datetime):
start timestamp for narrowing down search timeframes, defaults to None
end (datetime.datetime):
end timestamp for narrowing down search timeframes, defaults to None
file_size (int):
filter by result file size, measured in KB, defaults to None
result_count (int):
filter by result count, defaults to None
query_duration (int):
filter by query duration, measured in milliseconds, defaults to None
error_condition (bool):
filter by if an error occurred or not, exclude for both, defaults to None
Returns:
list of matching search requests
Expand All @@ -165,11 +192,11 @@ def list(self,

def delete(self, request_id: str) -> int:
"""
Entirely remove a search request from the AuroraX
database. Administrators only.
Entirely remove a search request from the AuroraX database. Administrators only.
Args:
request_id: search request UUID
request_id (str):
search request UUID
Returns:
0 on success, raises error on failure
Expand Down
9 changes: 0 additions & 9 deletions pyaurorax/search/requests/_requests.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,15 +75,6 @@ def get_data(aurorax_obj, data_url, response_format, skip_serializing):


def get_logs(aurorax_obj, request_url):
"""
Retrieve the logs for a request
Args:
request_url: the URL of the request information
Returns:
the log messages for the request
"""
# get status
status = get_status(aurorax_obj, request_url)

Expand Down
Loading

0 comments on commit e174e47

Please sign in to comment.