data_tools.query.SunbeamClient

class data_tools.query.SunbeamClient(api_url: str = None)

Bases: object

Encapsulate a client connection to the Sunbeam API, UBC Solar’s custom data pipeline.

__init__(api_url: str = None)

Create a client to connect to the Sunbeam API.

Uses the SUNBEAM_URL environment variable if api_url is not set, or by default “api.sunbeam.ubcsolar.com”.

Methods

__init__([api_url])	Create a client to connect to the Sunbeam API.
distinct(key, filters[, timeout])	Obtain the distinct values of a given key, subject to a filter.
get_file([origin, event, source, name, ...])	Get a File from the Sunbeam API.
is_alive([timeout])	Verify if the Sunbeam API is available.

Attributes

cache

Acquire an interface to the Sunbeam Cache API, descended from this client.

property cache

Acquire an interface to the Sunbeam Cache API, descended from this client.

distinct(key: str, filters: dict[str, str], timeout: float = 5) → list[str]

Obtain the distinct values of a given key, subject to a filter.

For example, if you want to see the distinct events processed by a certain pipeline, you can set key to “event” and filter to {“origin”: “your_pipeline”}.

As another example, if you wanted to see the events processed by a certain pipeline where the “power” stage was processed, you can set key to “event” and filter to {“origin”: “your_pipeline”, “source”: “power”}.

Parameters:

• key – Name of the field for which we want to get the distinct values.

• filters – A mapping which filters the query to have items match this filter’s values by field.

• timeout – The amount of time to wait for a request to return.

Raises:

requests.exceptions.Timeout – If the request times out.

Returns:

The values corresponding the key field of matching items.

get_file(origin: str = None, event: str = None, source: str = None, name: str = None, path: CanonicalPath = None, timeout: float = 5) → Result[File | Exception]

Get a File from the Sunbeam API.

You must provide either a CanonicalPath object directory by setting path, OR provide ALL the individual path elements origin, event, source, and name.

Returns:

A Result wrapping a File or an Exception

Parameters:

timeout – The amount of time to wait for a request to return.

Raises:

• requests.exceptions.Timeout – If the request times out.

• AssertionError – If path was not provided and any of origin, event, source, name are None.

is_alive(timeout: float = 0.5)

Verify if the Sunbeam API is available.

Parameters:

timeout – The time to wait for a response.

Returns:

True if the Sunbeam API is available, and False otherwise.