Reference

roarquery.runs

Query and return ROAR runs.

roarquery.runs.filter_run_dates(runs, started_before=None, started_after=None)

Filter runs by date.

Parameters:

• runs (List[Dict[str, Any]]) – The runs to filter.

• started_before (date, optional, default=None) – Return only runs started before this date.

• started_after (date, optional, default=None) – Return only runs started after this date.

Returns:

The filtered runs.

Return type:

List[Dict[str, Any]]

Examples

>>> runs = [
...     {
...         "CreateTime": "2020-01-01T00:00:00.000Z",
...         "Data": {
...             "name": "run-1",
...             "timeStarted": "2020-01-01T00:00:00.000Z",
...             "classId": "class-1",
...             "completed": "true",
...         },
...         "ID": "run-1",
...         "Path": "prod/roar-prod/runs/run-1",
...         "ReadTime": "2020-01-01T00:00:00.000Z",
...         "UpdateTime": "2020-01-01T00:00:00.000Z",
...     },
...     {
...         "CreateTime": "2020-02-01T00:00:00.000Z",
...         "Data": {
...             "name": "run-2",
...             "timeStarted": "2020-02-01T00:00:00.000Z",
...             "classId": "class-2",
...             "completed": "true",
...         },
...         "ID": "run-2",
...         "Path": "prod/roar-prod/runs/run-1",
...         "ReadTime": "2020-02-01T00:00:00.000Z",
...         "UpdateTime": "2020-02-01T00:00:00.000Z",
...     },
... ]
>>> filtered = filter_run_dates(runs, started_before=date(2020, 1, 15))
>>> print(filtered == [runs[0]])
True

roarquery.runs.get_runs(return_trials=False, query_kwargs=None, started_before=None, started_after=None, user_type='users', merge_user_info=True)

Get all runs that satisfy a specific query.

Parameters:

• return_trials (bool, optional, default=False) – If True, return the trials for each run as well.

• query_kwargs (dict, optional, default=None) – The query to run. If None, all runs will be returned.

• started_before (date, optional, default=None) – Return only runs started before this date.

• started_after (date, optional, default=None) – Return only runs started after this date.

• user_type (str, optional, default="users") – The user type to query. Either “users” or “guests”.

• merge_user_info (bool, optional, default=True) – If True, merge the user doc info into the run data.

Returns:

The runs that satisfy the query.

Return type:

List[dict]

roarquery.runs.get_runs_compat(root_doc='prod/roar-prod', return_trials=False, query_kwargs=None, started_before=None, started_after=None, merge_user_info=False)

Get all runs that satisfy a specific query.

Parameters:

• root_doc (str, optional, default="prod/roar-prod") – The Firestore root document. The returned runs will all be under this document.

• return_trials (bool, optional, default=False) – If True, return the trials for each run as well.

• query_kwargs (dict, optional, default=None) – The query to run. If None, all runs will be returned.

• started_before (date, optional, default=None) – Return only runs started before this date.

• started_after (date, optional, default=None) – Return only runs started after this date.

• merge_user_info (bool, optional, default=False) – If True, merge the user doc info into the run data.

Returns:

The runs that satisfy the query.

Return type:

List[dict]

roarquery.runs.get_trials_from_run(run_path)

Get all trials from a run.

Parameters:

run_path (str) – The Firestore path to the run.

Returns:

The trials from the run.

Return type:

List[Dict[str, str]]

roarquery.runs.get_user_from_run(run_path, legacy=False)

Get the user that owns a run.

Parameters:

• run_path (str) – The Firestore path to the run.

• legacy (bool, optional) – If True, the returned user will be identified by PID, otherwise the user will be identified by roarUid. Default: False.

Returns:

The user that owns the run.

Return type:

List[Dict[str, str]]

roarquery.runs.merge_data_with_metadata(fuego_response, metadata_params)

Merge trial data with metadata.

We often want to merge the run/trial data with some of the metadata returned by Firestore. In Python 3.9 we could use the | operator but we want to be backward compatible so we iterate over the data and metadata and merge them together.

Parameters:

• fuego_response (List[Dict[str, Any]]) – The trial data.

• metadata_params (Dict[str, str]) – The metadata fields that will be merged into the data. The keys are the desired keys in the merged data and the values are the metadata keys to use.

Returns:

The merged data.

Return type:

List[Dict[str, Any]]

roarquery.collections

Query Firestore collections.

roarquery.collections.get_collections()

Get collections from a database.

Return type:

List[str]

roarquery.utils

Utilities functions.

roarquery.utils.bytes2json(bytes)

Convert bytes to json.

Parameters:

bytes (bytes) – The bytes to convert.

Returns:

The converted json.

Return type:

List[_FuegoResponse]

Examples

An empty string will return an empty list: >>> bytes2json(b””) []

>>> json_out = bytes2json(
...    b'[{"ID": "1", "Data": {"a": "b"}, "Path": "prod/roar-prod", '
...    b'"CreateTime": "2020-04-01T00:00:00Z", '
...    b'"ReadTime": "2020-04-01T00:00:00Z", '
...    b'"UpdateTime": "2020-04-01T00:00:00Z"}]'
... )
>>> print(json_out == [{
...     'ID': '1',
...     'Data': {'a': 'b'},
...     'Path': 'prod/roar-prod',
...     'CreateTime': '2020-04-01T00:00:00Z',
...     'ReadTime': '2020-04-01T00:00:00Z',
...     'UpdateTime': '2020-04-01T00:00:00Z'
... }])
True

roarquery.utils.camel_case(string)

Convert a string to camel case.

Parameters:

string (str) – The string to convert.

Returns:

The camel case string.

Return type:

str

Examples

>>> camel_case("an_example_string")
anExampleString

>>> camel_case("an-example-string-with-dashes")
anExampleStringWithDashes

roarquery.utils.drop_empty(iterable)

Drop empty strings from a list.

Parameters:

iterable (list) – The list to drop empty strings from.

Returns:

The list with empty strings dropped.

Return type:

list

Examples

>>> drop_empty(["", "a", "", "b"])
['a', 'b']

roarquery.utils.page_results(query, limit=None)

Page through results from a query.

Parameters:

• query (List[str]) – The query to run. This is a list of strings that will be passed to subprocess.check_output.

• limit (int, optional, default=100) – The number of results to return per page.

Returns:

The results of the query.

Return type:

List[_FuegoResponse]

roarquery.utils.trim_doc_path(path)

Remove leading project information from firestore document path.

Parameters:

path (str) – The path to standardize.

Returns:

The standardized path.

Return type:

str

Examples

>>> trim_doc_path("projects/proj-id/databases/(default)/documents/prod/roar-prod")
prod/roar-prod